Need to create an api doc for an existing application written with nodejs/express

Question

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.

Answer 1

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.