@origins-digital/nestjs-swagger

A NestJS package that provides enhanced Swagger/OpenAPI integration with Zod schema support.

Installation

npm install @origins-digital/nestjs-swagger

Features

• Seamless integration with NestJS Swagger
• Automatic Zod schema to OpenAPI conversion
• Support for DTOs created with @origins-digital/zod-openapi-utils
• Custom Swagger UI configuration
• Bearer token authentication support
• Automatic API documentation generation

Usage

Basic Setup

import { Module } from '@nestjs/common';
import { initSwagger } from '@origins-digital/nestjs-swagger';

@Module({})
export class AppModule {
  constructor(private readonly app: INestApplication) {
    initSwagger(app, 'My API', '1.0.0');
  }
}

Advanced Configuration

import { Module } from '@nestjs/common';
import { initSwagger } from '@origins-digital/nestjs-swagger';
import { UsersModule } from './users/users.module';

@Module({})
export class AppModule {
  constructor(private readonly app: INestApplication) {
    initSwagger(
      app,
      'My API',
      '1.0.0',
      {
        // Additional schemas to include in the documentation
        CustomSchema: {
          type: 'object',
          properties: {
            id: { type: 'string' },
            name: { type: 'string' },
          },
        },
      },
      'api-docs',
      [UsersModule],
    );
  }
}

Using with Zod DTOs

import { z } from 'zod';
import { createZodDto } from '@origins-digital/zod-openapi-utils';

const UserSchema = z
  .object({
    id: z.string().uuid(),
    name: z.string(),
    email: z.string().email(),
  })
  .openapi({ title: 'User' });

export class CreateUserDto extends createZodDto(UserSchema) {}

@Controller('users')
export class UsersController {
  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    // The DTO will be automatically documented in Swagger
    return this.usersService.create(createUserDto);
  }
}

Configuration Options

The initSwagger function accepts the following parameters:

• app: The NestJS application instance
• packageName: The name of your API
• version: The API version
• schemas: Optional additional OpenAPI schemas to include
• uri: Optional custom Swagger UI path (defaults to 'docs')
• modules: Optional array of modules to include in the documentation

API Documentation

The Swagger UI will be available at:

• Default: http://localhost:3000/docs
• Custom: http://localhost:3000/{uri}

The OpenAPI specification will be available at:

• http://localhost:3000/docs-json

Dependencies

• @nestjs/swagger: ^7.3.0
• @origins-digital/zod-openapi-utils: ^0.0.5

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.