CODEWITHSUNDEEP
node.jsrestexpressdocumentationswagger
Manatax
Manatax

Reputation: 4223

Can Swagger autogenerate its yaml based on existing express routes?

I inherited an existing API and I would like to document it with swagger, but I don't yet know the full scope of it. Can Swagger (or another middleware/tool) auto-magically generate the yaml (for swagger) based on the existing express routes?

For what I saw on other questions, it would appear that this is mostly a manual job, but I'm double-checking if someone here found a way around this.

Upvotes: 62

Views: 52230

Answers (7)

aes
aes

Reputation: 95

I wrote express-openapi-gen to solve this problem for myself. It is still in pre-release so no guarantees it will support everything you need, but I am accepting contributions.

app.get("/banana/:count",
    // use JSDoc for JS
    (req: express.Request<{ count: string }, string>, res) => {
        res.send([...Array(Number(req.params.count))].map(_ => "🍌").join(''));
    });

Unlike the examples above (from those I have tried),

  • this package does not rely on comments to generate documentation.
    • If you have no types, it will still identify and map all your routes, identifying route parameters and giving you loosely typed request bodies for HTTP methods that accept them. If you choose to use types (or annotate them with JSDoc), you do so using the interfaces from @types/express and @types/express-serve-static-core, which you may already be using.
  • it builds the document from your source code at runtime, not from analyzing the requests after they happen

(I realize this is an ancient post but I visited this question multiple times trying to find an answer so I thought I'd share my solution.)

I wrote this to try to recreate Swashbuckle.AspNetCore in express and it is still woefully incomplete due to struggles with strong type inference in JSDoc / TypeScript. I am looking into ts-pattern, but I will likely try to convince my team to switch to using C# minimal APIs instead.

Upvotes: 0

kato2
kato2

Reputation: 593

You can use swagger-autogen, a tool that allows you to customize the types using comments. The drawback is that you must lose time learning how to add documentation.

Upvotes: 0

Miguel Gamboa
Miguel Gamboa

Reputation: 9353

With express-sitemap-html you may automatically generate a minimalistic Open API definition (only including route parameters) and install a Swagger UI for all routes of an existing express app. You only need:

const sitemap = require('express-sitemap-html')
...
sitemap.swagger('Your app name', app) // given that app is an express instance

Instead of analyzing HTTP requests at runtime, this approach inspects express app instance and mounted routes.

PROs you don't need to perform ahead requests to get an updated list of available routes.

CONs it provides untyped parameters features.

Upvotes: 3

ovidiu-miu
ovidiu-miu

Reputation: 57

Have a look to swagger-jsdoc. It's a different approach.

The docs stick to the code, and also lets the express code to remain pure.

Guides:

Upvotes: 0

mpashkovskiy
mpashkovskiy

Reputation: 298

There is an option: you can embed middleware that will analyse all requests and responses and generate specification for you: https://github.com/mpashkovskiy/express-oas-generator

Then you can use it through your's app Swagger UI like http://host:port/api-docs

Upvotes: 7

Dariusz Filipiak
Dariusz Filipiak

Reputation: 3124

Yes !!!. You can use this awesome project typescript-test. Here is sample app. Clone it, run npm i,npm run swagger and go to /dist/swagger.json. Done. Swagger yaml and json is generated based on express routes !

Upvotes: 3

Mike
Mike

Reputation: 11545

I have experience in BOTH auto-generating the Swagger json and manually writing it out for an API that I helped build. Here are the pros/cons of both based on my experience.

Swagger AUTOMATIC Documentation Generation:

We used the swagger-node-express module in combination with swagger-ui. https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui

Pros

Super easy to document. Just throw a few lines above the resource definition and the documentation (json) is automatically generated by the module.

Cons

You are no longer using straight up Express when you use this package. Your route definitions have to be defined through the Swagger module and this pulls you away from vanilla Express.

Swagger MANUAL Documentation Generation:

We just pulled swagger-ui into the project and wrote the documentation manually.
https://github.com/swagger-api/swagger-ui

Pros

This approach decouples the documentation from the Express framework. Express endpoints are written as they normally would be written and the Swagger documentation is defined separate from the Express framework. Allows you to write pure express.

Cons

Documentation changes become a little more tedious due to the fact that you are manually writing and changing the yaml or json yourself. It's a little bit harder than just updating a few lines of code above a resource. This approach is also a little more prone to documentation typos and errors due to the fact it is entirely manually typed.

If you are planning to manually write your swagger documentation use the swagger editor below to validate your manual docs.
http://editor.swagger.io/#/

Conclusion

For this API project, we started out by auto-generating the documentation using the swagger-node-express package. However, we realized that decoupling the swagger documentation from the express library was important to enable us to use all the features and functionality of Express. I recommend manually writing the docs to have full control over both the Swagger documentation and the Express web framework that your app will use.

Upvotes: 63

Related Questions