-
Notifications
You must be signed in to change notification settings - Fork 66
Add RESTful API Spec Generator #285
Comments
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? |
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. |
Pull requests are welcome. |
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.. |
@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. |
Forgot to ask around. I'll do so next week.. |
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? |
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. |
@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 |
@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. |
@kefo thks a lot! |
@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. |
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. |
@garyrusso 28msec/marklogic-connector#7 still shows the content of the deleted generate_swagger.jq in case you are still looking for it.. |
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
The text was updated successfully, but these errors were encountered: