How to generate swagger API doc from TypeScript based Express app?

Question

I am able to configure swagger url using the Express API with autogenerated OpenAPI doc through Swagger article.

I am using TypeScript and it generates .js files under dist which does not have any API doc comments added. Pointing apis: ['../dist/*.js'] nor to Route.ts generates the API details. I am not using any rest decorator.

/**
 * @swagger
 * /:
 *    get:
 *      description: This should return ok
 */
this.router.get("/", (req: Request, res: Response) => this.api.process(req, res));

The Routes.ts API doc looks like the above. How to generate swagger doc from this?

Solution

I would recommend that you use a library that handles everything for you such as tsoa which can easily generate Swagger/OpenAPI documents from your TypeScript types. It also does the runtime validation for you so that you know the request actually is the type that TypeScript says it should be. The readme contains all of the setup information that you would need to start using it. It's compatible with express, hapi, koa, and more:

https://github.com/lukeautry/tsoa

---

(Full Transparency: I am one of the maintainers of tsoa. But I was first a consumer of tsoa and I find it to be a great product... that's why I asked to help maintain it! :) )

Comments

[johndoe]

I went with manually writing the yml file for the API and used redoc to generate the html file. Could not get the types and annotations to work properly within the limited time.

[Zag Gol]

There is also the same solution for hapi server (not express)?

[G Dan]

can tsoa generate OpenAPI docs from pure Typescript i.e. just an interface or class? I skimmed the docs and it seems to require a Node app in order to generate the OpenAPI docs

[Jonathan]

@ZagGol: tsoa seems to support a number of middleware solutions, including Hapi. Check out middlewaresHapiController.ts from tsoa's tests

[Juan Sánchez]

Can Tsoa only generate swagger + validation without generating routes? I couldn't find any example without routes generation