Quick Start
Generate your first OpenAPI spec in minutes
Generate an OpenAPI specification from your NestJS application in three steps.
Step 1: Create a Config File
Create openapi.config.ts in your project root:
import { } from 'nestjs-openapi';
export default ({
: 'openapi.json',
: {
: 'src/app.module.ts',
: 'tsconfig.json',
: 'src/**/*.dto.ts',
},
: {
: {
: 'My API',
: '1.0.0',
},
},
});Paths are resolved relative to this config file. files.tsconfig is required and should point to the tsconfig that includes your app sources and path aliases. dtoGlob is optional; use it to include DTOs that are not referenced directly by controller signatures.
Output can be JSON or YAML (format: 'yaml'). Define security schemes in the
config file; decorators add per-operation requirements.
Step 2: Generate the Spec
Run the CLI:
npx nestjs-openapi generate -c openapi.config.tsYou'll see output like:
✓ Generated openapi.json (1.2s)
42 paths, 87 operationsStep 3: View the Result
Your openapi.json file is ready. You can:
- View it in Swagger Editor
- Import it into Postman
- Generate API clients
- Serve it with Swagger UI
Add to package.json
{
"scripts": {
"openapi": "nestjs-openapi generate -c openapi.config.ts",
"prebuild": "npm run openapi"
}
}Use --debug flag for troubleshooting: npx nestjs-openapi generate -c openapi.config.ts --debug
Example Output
For a simple controller:
@Controller('users')
export class UsersController {
@Get()
findAll(): User[] {
return [];
}
@Get(':id')
findOne(@Param('id') id: string): User {
return null;
}
@Post()
create(@Body() dto: CreateUserDto): User {
return null;
}
}The generated spec includes:
{
"paths": {
"/users": {
"get": { "operationId": "UsersController_findAll" },
"post": { "operationId": "UsersController_create" }
},
"/users/{id}": {
"get": { "operationId": "UsersController_findOne" }
}
}
}Operation IDs default to <Controller>_<method>. Override with @ApiOperation({ operationId }) when you need stable names.