Generate Swagger documentation as JSON/YAML in NestJS
Open Source Package for Better Swagger Experience in NestJS Projects
New NestJS Swagger Generator evolved than ever
Can we please not normalize mocking people whoβs first language is not English.
Samchon is producing some pretty amazing stuff with typia/nestia. I was able to take raw types, and enable validation across my entire backend with a simple find -> replace decorator swap. No defining zod schemas, no language server performance woes. It just works as youβd hope typescript would out of the box. Plus free OpenAPI defs, and a fully typed client for usage on the frontend. All for free.
@SamchonFramework youβre just missing a few words:
OpenAPI (Swagger) document generator for NestJS evolved than ever.
To
OpenAPI (Swagger) document generator for NestJS is more evolved than ever.
More on reddit.comBetter workflow for API Testing with Swagger/Postman
Β» npm install @nestjs/swagger
According to this github issue you can just stringify the created Swagger document and e.g. write it to the file system like this:
const app = await NestFactory.create(ApplicationModule);
const options = new DocumentBuilder()
.setTitle("Title")
.setDescription("description")
.setVersion("1.0")
.build();
const document = SwaggerModule.createDocument(app, options);
fs.writeFileSync("./swagger-spec.json", JSON.stringify(document));
SwaggerModule.setup("/api", app, document);
await app.listen(80);
Tested in Nestjs v9
Suppose the docs path is as follows
http://localhost:3000/docs
Get JSON
http://localhost:3000/docs-json
Get YAML
http://localhost:3000/docs-yaml
Hey devs! π
I developed an open source npm package to solve some issues in my team which has NestJS projects. Additionally, I developed eslint plugin based by this package. It will be also good to take feedbacks from you if same approach can be used for express or node.
My team was working on a massive NestJS project. The API surface kept growing, deadlines were always around the corner, and ensuring our Swagger documentation was accurate felt like trying to hold water in our hands. You fix one issue, and two more slip through the cracks.
While we are using ApiOperation decorator we started to forgot adding endpoint description or title. While we are using ApiProperty for members of endpoint payload or endpoint parameters, we forgot to add description, type etc. Then Swagger Documentation for our api's started to seem inconsistent, titles have different writing style, sometimes descriptions missed etc.
So then we had issues like below:
-
Missed endpoint titles or descriptions.
-
Different pattern for description of several endpoints.
-
Long code review times, due to warn each other to add missed swagger descriptions etc.
-
Unclear error responses, causing confusion for API consumers.
-
Missed helper usages like adding `type`, `required` in decorators like `@ApiParam` etc.
-
The sinking feeling when QA flagged issues that couldβve been avoided with better documentation.
-
Deprecated endpoints still showing up in the docs.
And so, nest-swagger-checker was bornβa tool that scans your NestJS project for Swagger annotation issues. Think of it as your friendly API documentation guardian.
What It Does:
β
Detects missing or incomplete Swagger annotations.
β
Warns about unused or outdated annotations.
β
Integrates seamlessly with your CI pipeline to catch issues before they reach production.
β
Warns about missed endpoint titles, descriptions, and missing API parameter descriptions.
β
Suitable for working with ESLint, providing real-time warnings to developers in the IDE through ESLint.
β
Fully configurable structure:
-
Specify which type of endpoints (e.g., POST, GET) should be checked.
-
Configure checks for request bodies, query parameters, or both.
Why It Matters:
After integrating it into our workflow, we noticed immediate results. Not only were our docs more reliable, but our team also saved hours of manual review. It gave us peace of mind, knowing our API consumers would have a smoother experience.
Open Source & Ready for You!
Weβre sharing this tool with the community because we believe it can save you the headaches we faced. Check it out here: GitHub - Trendyol/nest-swagger-checker and GitHub - Nest Swagger Checker Lint here for Eslint plugin.
Iβve also detailed article for this package if somone wonders whole history : Medium Article
Iβd love to hear your thoughts! Have you faced similar struggles? What are your best practices for maintaining Swagger documentation? Letβs discuss and make API docs better, together! π