[xquery-talk] Xquery and API documentation
adam.retter at googlemail.com
Wed Apr 24 06:21:51 PDT 2013
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.
On 24 April 2013 13:40, Jakob Fix <jakob.fix at gmail.com> wrote:
> 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  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,
>  https://developers.helloreverb.com/swagger/
> talk at x-query.com
More information about the talk