[xquery-talk] Xquery and API documentation

[Adam Retter]

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 <jakob.fix at gmail.com> 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/
>
>
> _______________________________________________
> talk at x-query.com
> http://x-query.com/mailman/listinfo/talk



-- 
Adam Retter

skype: adam.retter
tweet: adamretter
http://www.adamretter.org.uk