Hi Jakob, I also recently saw Swagger and was very impressed and was considering doing something with it at some point.
The XQuery 3.0 annotations for defining a REST API are known as RESTXQ. If the platform you are using supports RESTXQ and introspection, then you could probably quite easily write a small XQuery script to find the annotated functions and create the JSON file for Swagger. If your on eXist you could probably even write the function as a RESTXQ function, making the api-doc a REST API function too :-) Another option would be if you have RESTXQ support but no introspection, to use rest:resource-functions() function to get the details of the annotated functions and then create JSON from that. Cheers Adam. On 24 April 2013 13:40, Jakob Fix <[email protected]> wrote: > Hi, > > I'm looking for ways to generate API documentation from our Xquery code. Of > course, there is Xqdoc, but I'm looking to get something that is a) a bit > better-looking and more importantly, b) usable by the developer who wants to > try out the API. > > I've been looking at Swagger [1] which seems to do what I want. It expects a > JSON file that would need to be generated from the Xquery code. I think I > remember Adam Retter giving a talk on how to use 3.0 annotations for > defining the API in Prague a couple of years ago. > > Are there already efforts underway to get something like this going? > > I would be most interested, > Jakob. > > [1] https://developers.helloreverb.com/swagger/ > > > _______________________________________________ > [email protected] > http://x-query.com/mailman/listinfo/talk -- Adam Retter skype: adam.retter tweet: adamretter http://www.adamretter.org.uk _______________________________________________ [email protected] http://x-query.com/mailman/listinfo/talk
