Generating swagger docs from typescript interfaces

Question

I'm using swager-jsdoc to document all the DTOs of the app.

I was wondering is there any way to generate the swagger docs automatically from typescript interfaces.

I have a lot of them in the project and also a lot of mongoose schemas and models. It is getting tedious to keep them in sync. On the other hand I do not want to use the swagger generation tools. I prefer the bottom-up approach.

Cheers

Found a related question but for generating mongoose schemas. It'd would be nice to shoot two rabbits with one bullet. — Adrian Moisa
– Adrian Moisa, Commented Dec 1, 2018 at 14:01
Found typegoose. That solves half the problem :D Still searching for the swagger counterpart. — Adrian Moisa
– Adrian Moisa, Commented Dec 1, 2018 at 14:08

Patrick Fowler · Accepted Answer · 2021-10-25 23:39:26Z

9

Another option to tsoa is routing-controllers + routing-controllers-openapi. The main difference between the two (AFAIK) is that tsoa relies on code generation whereas routing-controllers operates wholly on runtime. Both methods have their upsides: tsoa is able to e.g. utilize richer metadata (such as code comments) whereas with routing-controllers we can skip the generation step. My recommendation is to check both out!

One more option is typescript-json-schema, which generates JSON Schema out of Typescript interfaces; after you have defined your models in JSON Schema you're not terribly far off from an OpenAPI spec.

edited Oct 25, 2021 at 23:39

Patrick Fowler

1764 silver badges13 bronze badges

answered Aug 13, 2019 at 15:01

Aleksi

5,14639 silver badges51 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Nikos Over a year ago

Be aware that TSOA currently does not currently support route specific middlewares. Also routing-controllers-openapi does not seem as feature rich as TSOA.

Douglas Gaskell Over a year ago

TSOA also has many type limitations. We need some SO answers/discussion around the methodology of programmatically working with TS types so we can improve existing libraries with better support.

GreeneCreations · Accepted Answer · 2023-07-15 13:17:14Z

8

Yes, you can easily generate Swagger and OpenAPI documents from your TypeScript types by using tsoa. 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~ was 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! :) ) I’ve since stepped back, but the new maintainers are awesome!

edited Jul 15, 2023 at 13:17

answered Aug 13, 2019 at 14:15

GreeneCreations

1,2721 gold badge12 silver badges20 bronze badges

4 Comments

Andrew Miracle Over a year ago

Why does tsoa not support route specific middleware at the moment. Also is there a workaround for this particular feature?

GreeneCreations Over a year ago

That’s a question thats better suited as a github issue as a feature request of tsoa. But the short answer is type safety. Ask the new maintainer of tsoa in their github and you might get a different answer.

Gowsik Over a year ago

@GreeneCreations can i use tsoa with Lambd Proxy event

GreeneCreations Over a year ago

@GowsikKC, I don’t know.

Ricardo Emerson · Accepted Answer · 2020-08-13 23:22:08Z

2

Another option is use https://www.npmjs.com/package/ts-to-openapi to generate Swagger Schemas From the interfaces.

Example: Considering the User interface bellow:

export interface User {
  name: string;
  email: string;
  nickname?: string;
}

In terminal run the followed command:

npx ts-to-openapi -f User.ts -t User >> User.ts

After this your interface User will be updates as bellow:

export interface User {
  name: string;
  email: string;
  nickname?: string;
}

/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       additionalProperties: false
 *       properties:
 *         email:
 *           type: string
 *         name:
 *           type: string
 *         nickname:
 *           type: string
 *       required:
 *         - name
 *         - email
 *       type: object
 */

answered Aug 13, 2020 at 23:22

Ricardo Emerson

90610 silver badges12 bronze badges

1 Comment

Patrick Fowler Over a year ago

The ts-to-openapipackage is “no longer heavily maintained,” and the project page points to the more active and comprehensive typeconv package which supports more than just ts/openAPI generation

Collectives™ on Stack Overflow

Generating swagger docs from typescript interfaces

3 Answers 3

2 Comments

4 Comments

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

2 Comments

4 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related