61

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.

EJoshuaS - Stand with Ukraine
  • 11,977
  • 56
  • 49
  • 78
Manatax
  • 4,083
  • 5
  • 30
  • 40
  • Update: I ended up using [swagger-ui](http://swagger.io/swagger-ui/) and simply filled the json documentation with the endpoints manually. Once you figure out how it works, it's as simple as using postman, but it makes is available for third parties than need to interact with your code. – Manatax May 17 '17 at 01:07

7 Answers7

63

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.

Mike
  • 10,297
  • 2
  • 21
  • 21
  • 4
    Thank you Mike, I understand those methods, but I don't consider the first one to really be "auto-magic" in the sense that I still need to define most of the case. I'm looking for something that would basically interpret the routes and generate something like the manual doc and I would be ok with filling in the blanks of what It cannot interpret from the code itself. – Manatax Jul 10 '15 at 17:39
  • 2
    It has been two days searching, but I haven't found an end-to-end working solution. http://www.npmjs.com/package/expressjs-api-explorer looks promising but is buggy and did not work for me. Idea is to generate output using API-Explorer library and convert to YAML that swagger expects, then use one of the many libraries like suggested by Mike that work with static YAML files. – Arvind Singh Aug 28 '16 at 12:38
  • 1
    Did yo find a good solution to this problem? I tried using [Swagger-Node-Express-For-Existing-APIs](https://github.com/shawngong/Swagger-Node-Express-For-Existing-APIs), but didn't work. – rahil471 Nov 20 '16 at 13:43
  • We went the manual way. It was not that tragic, and after 2-3 days, we had full documentation of over 300 endpoints. – Manatax Dec 19 '17 at 02:21
  • 2
    @Mike - The problem with the manual approach is that you're moving the documentation away from the code. In my experience, this almost inevitably leads to stale documentation at some point (which can be worse than no documentation), because now you have to maintain the doc in a separate place. The best way to keep documentation current is to keep it as close the code as possible. At the end of the day, the code is what will survive, so whatever important artifacts we must preserve stand the best chance of surviving if they're bolted onto the code. – dcp Jan 31 '18 at 19:17
  • I built an open-source tool to help with the doc-drift problem. It is kind of like Git for APIs. It uses a local proxy to analyze real development traffic and updates your API spec when it observes new behavior in the API. https://github.com/opticdev/optic – centree Nov 19 '19 at 13:52
  • is there any solution for this yet? – olawalejuwonm Jul 28 '23 at 02:19
7

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

mpashkovskiy
  • 288
  • 3
  • 3
  • Can you add snippets of code demonstrating how the OP would go about this? – Marcello B. Dec 16 '17 at 19:10
  • Sorry didn't your question. If you are asking about express-oas-generator module then the only thing you need is . `expressOasGenerator.init(app, {});` If you are asking about details of implementation then here is the main init routine: https://github.com/mpashkovskiy/express-oas-generator/blob/master/index.js#L291 – mpashkovskiy Dec 17 '17 at 16:12
  • He doesn't feel like this answers my question... and neither do I. This is a hack, but not a solution. I can't wait for someone else to use my endpoints to know what they are. There is a potential for many of them not get discovered until it's to late. – Manatax Dec 19 '17 at 02:13
  • You are right it is a hack. There are two options: either you write spec file by yourself or you use the hack and have all endpoints partially documented. – mpashkovskiy Dec 19 '17 at 12:16
  • @mpashkovskiy - Not sure if you do any C# work, but there is a nuget library called Swashbuckle which can generate the swagger doc without requiring you to actually run the requests. And it will even use your XML comments above each method to document the rest operations and parameters. This may be hard to do with javascript though. – dcp Jan 31 '18 at 19:29
  • @dcp I actually do, thanks for pointing me out - will try it. Well it is true that in strongly typed languages you can analyse method's arguments and return values and build schema out of it. – mpashkovskiy Feb 02 '18 at 13:59
3

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 !

Dariusz Filipiak
  • 2,858
  • 5
  • 28
  • 39
  • 1
    I don't have access to that repo anymore (we went the manual route at the time). But I would have loved the opportunity to test this. What exploration method does it use? – Manatax Dec 19 '17 at 02:15
  • I see it requires typescript and it depends on annotations to "guess" the routes. I don't think it would have worked for that one. – Manatax Dec 19 '17 at 02:17
3

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.

Miguel Gamboa
  • 8,855
  • 7
  • 47
  • 94
0

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:

ovidiu-miu
  • 57
  • 2
  • 9
0

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.

kato2
  • 535
  • 4
  • 15
0

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.

aes
  • 55
  • 1
  • 7