Add RESTful API Spec Generator

[garyrusso]

Add Swagger or equivalent spec generator tool so that the RESTful API spec can be auto-generated.

Here's an example. => http://petstore.swagger.wordnik.com/#!/pet

[dmcassel]

Hi Gary. The out-of-the-box REST API spec is available at DMC, so I'm guessing you are interested in creating a spec for the extensions. Is that correct?

[garyrusso]

Hello Dave - Yes, I was thinking that auto-generating the API Spec from the code would be a productivity boost for developers. I've been spending too much time manually documenting the API Spec using GitHub markdown like this. => https://github.com/garyrusso/GLM-Search#restful-apis

This API Spec would be nicer looking and more accurate if auto-generated.

I noticed that swagger is pretty popular with both the .Net and the Java folks. => http://swagger.io/

If I get some free time, I may try to add it to my roxy fork and will let you know.

[dmcassel]

Pull requests are welcome.

[grtjn]

I'm aware of an internal project in which docs for REST extensions is generated (exposed with a REST extension). I'd have to take a closer look though. Paxton, you are working on that project as well now..

[wcandillon]

@grtjn Is the documentation at https://docs.marklogic.com/REST/GET/v1/search available in docbook or similar format? If yes it would be fairly trivial to transform it into swagger.

[grtjn]

Forgot to ask around. I'll do so next week..

[grtjn]

From what I have discovered myself so far it doesn't look like it is in DocBook.

@dmcassel Would it be interesting to put Swagger(like) docs on DMC itself?

[dmcassel]

The /v1/config/resources endpoint documents what extensions are available and, if provided, what parameters they take. Seems like a Swagger plugin could be built to provide docs in that format.

@grtjn, I think it might be odd to have the current docs plus a Swagger version of them on the same site. However, the data needed to generate a Swagger version is (I think) all contained in the zipped version of the docs.

[wcandillon]

@garyrusso I'm not sure if this helps but I've wrote a query that crape the marklogic website to generate a swagger 2.0 spec: https://github.com/28msec/marklogic-connector/blob/wcandillon/queries/private/generate_swagger.jq

Here's an output example: https://dl.dropboxusercontent.com/u/1487285/marklogic-spec.json

[kefo]

@wcandillon @garyrusso You can download all the MarkLogic documentation here: https://docs.marklogic.com/MarkLogic_8_pubs.zip (available from here https://docs.marklogic.com/)

Once you unzip it, take a look at this file:

/pubs/raw/apidoc/RESTclient.xml

It's not docbook, but it's XML and has to be easier than scrapping the HTML.

[wcandillon]

@kefo thks a lot!

[garyrusso]

@wcandillon Did you move the swagger generator code?

https://github.com/28msec/marklogic-connector/blob/wcandillon/queries/private/generate_swagger.jq

I was hoping to do something with it.

[grtjn]

I think this is a nice to have, but more like a potential plugin of some kind, rather than something baked into Roxy (Deployer) itself. I could see someone put an MLPM package together or such, which either directly returns swagger docs based on installed rest options/extensions, or provides a lib that makes it trivial to get that.

Encouraging people to take a stab at this, but closing this Roxy ticket.