8

I have a few private apis written in plain old express. Time to let it out and provide some api documentation.

What I don't want (at least yet) it to re-write my express app to integrate api documentation into the code. Mainly since I am not sure what framework or spec to use to document my api I don't really want to be locking into one particular thing.

I would like to serve out the doc as part of a sub resource under my api (ie I do not want to run a different server or subdomain). Maybe '/api/docs'. A plus would also be a UI that I could embed within my app that could parse the docs and at the very least provide a nice presentation of the docs in html (api interaction is a plus).

Things like swagger-node are cool, but would require me to re-write all my express code to integrate swagger. At that point I have a big investment and am tightly coupled to swagger.

Is there a way to serve out swagger or iodocs or maybe something else to document my api in a way that is minimally invasive to existing routes?

EDIT:

I could serve out the Swagger spec from a hand written doc. Problem I see is that you have to define basePath in the swagger doc. This does not really allow me to easily deploy under different domains.

hong4rc
  • 3,999
  • 4
  • 21
  • 40
lostintranslation
  • 23,756
  • 50
  • 159
  • 262
  • 1
    You could always fire up notepad and manually write your documentation as an .html file :) Here are two lists that include many alternatives, such as [Mashery](http://www.mashery.com/product/io-docs): http://www.infoq.com/research/api-documentation – FoggyDay Dec 23 '14 at 03:38
  • 1
    you should know that there is a swagger ui too which will parse your specs and show it beautifully + api integration provided you write the specs according to swagger specification. – Sikorski Dec 23 '14 at 12:39
  • Thanks, I did see that there is a swagger-ui. Do you know if I can just add that as a dependency to an existing node project? – lostintranslation Dec 23 '14 at 14:50
  • 1
    swagger-ui is a set of static html files with js and css. There are also npm packages of it - https://www.npmjs.com/package/swagger-ui. – Ron Dec 23 '14 at 14:56

1 Answers1

7

There's a wide array of node.js tools to integrate Swagger with your application, and I assume they offer different ways of doing so. You can find a list of such integrations here - https://github.com/webron/swagger-spec/#nodejs - but I can tell you that there are additional tools out there that are not listed there. You can try searching github for swagger and node/express.

As for the manual spec and the basePath - Swagger 2.0 actually solves that for you. You can use the online editor - http://editor.swagger.io - to write your specs in a more human-friendly YAML form, which then you can export to JSON. Unlike Swagger 1.2 and previous versions, the basePath is now split into three properties - schemes (http, https), host (domain, port) and basePath (the root context of the application). None of these properties are mandatory, and they all default to whatever is serving the swagger.json file (the spec itself). schemes defaults to the scheme service the swagger.json, host defaults to the host used for serving the swagger.json and basePath will be \ unless explicitly specified. I believe this should solve your concerns regarding the basePath.

Ron
  • 14,160
  • 3
  • 52
  • 39
  • Wow, thanks. Do you know if you can spilt your swagger files into parts? I.E. one file for each resource and have the parts combined before serving out? – lostintranslation Dec 23 '14 at 14:49
  • 1
    In 2.0 you theoretically can, but there's an issue we need to resolve there so I wouldn't use that option just yet. For now, it's better to keep it all in a single file, though there are ways to ease up model, parameter and response repetitions. – Ron Dec 23 '14 at 14:54
  • I used http://editor.swagger.io . What should I do after writing YAML doc and then download the json swagger file ? I need to integrate it to my nodejs app. – Mostafa Khattab Jan 06 '16 at 13:53
  • @MostafaKhattab that depends on how you integrate it. If it's documenting an existing API, the way to combine the two would be using components that support a design-first approach like swagger-node. Otherwise, you'll need to host is independently without special integration. – Ron Jan 06 '16 at 22:19