Swagger-node-express usage

Question

I'd like to share my thoughts about https://github.com/swagger-api/swagger-node-express

It has 564 stars on Github, so I think it is justify to use it, but:

• Why should I use methods like addGet/addPost and split my controller by HTTP methods
• Why should I involve models to routing?
• I can use validators for authentication, but I have to choose some paths, that should be protected there. It duplicates logic , that stores in swagger json file.

Isn't the right way to have a static swagger.json and build Express routes on it? Or maybe I don't understand some practics

Answer 1

Swagger is just a spec. You could hand craft a swagger spec without any code, serve the spec to a swagger-ui compliant page, and it "will work." You could have a fully defined API and "run" it using the UI pages. Same is true for Express without swagger - you can do a lot of neat things! But some effort would be needed to document the API in swagger.

If you want to use swagger-node-express, you are coupling the code to the API documentation. This can save you a lot of time, and keep changes in the same file, etc. However, like all your questions allude to, you must do things the swagger-node-express way. Faster than doing both separately, but there are constraints one must follow.

There are other swagger packages that tackle this from different angles. I've seen some that try to build the swagger docs from the Express/Restify routes automagically. An alternative to swagger-node-express is swagger-tools , which even includes validation, but I'd guess you'd be limited in some fashion to writing Express without any swagger integrated.

You are free to build swagger docs manually (or with some YAML, jsDoc package or a generator), but that would take some extra time after your routes are written. Plus, it's a separate place to maintain your docs and invariably they will be out of sync at some point, if not abandoned. Using swagger-node-express is primarily a time saver and, even with its drawbacks, that might be worth the extra development effort of the alternatives.