@bvhoach2393/nest-swagger

A NestJS library for easy Swagger/OpenAPI documentation setup with environment variable configuration support.

Description

This library provides a simple and flexible way to configure Swagger documentation for NestJS applications. It supports environment variable configuration and includes both basic and authentication-enabled Swagger setups.

Features

• 🚀 Easy Swagger setup for NestJS applications
• 🔧 Environment variable configuration
• 🔐 Support for authentication in Swagger documentation
• ⚠️ Automatic warnings for missing environment variables
• 📝 TypeScript support with full type definitions
• 🧪 Comprehensive unit tests

Installation

Install the library

npm install @bvhoach2393/nest-swagger

Install peer dependencies

npm install @nestjs/swagger swagger-ui-express @nestjs/config

Environment Variables

The library reads the following environment variables:

• SWAGGER_TITLE - Title for your API documentation
• SWAGGER_DESCRIPTION - Description for your API documentation
• SWAGGER_VERSION - Version of your API
• SWAGGER_PATH - Path where Swagger UI will be available (e.g., 'api-docs')
• SWAGGER_API_DOC_PATH - Path for JSON documentation endpoint
• SWAGGER_TAG - Default tag for your API endpoints

Example .env file

SWAGGER_TITLE=My Awesome API
SWAGGER_DESCRIPTION=This is an awesome API for managing resources
SWAGGER_VERSION=1.0.0
SWAGGER_PATH=api-docs
SWAGGER_API_DOC_PATH=api-json
SWAGGER_TAG=api

Usage

1. Import the module in your app module

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { NestSwaggerModule } from '@bvhoach2393/nest-swagger';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    NestSwaggerModule,
    // ... other modules
  ],
})
export class AppModule {}

2. Setup Swagger in your main.ts

import { NestFactory } from '@nestjs/core';
import { NestSwaggerService } from '@bvhoach2393/nest-swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // Get the swagger service
  const swaggerService = app.get(NestSwaggerService);
  
  // Setup basic Swagger
  swaggerService.setupSwagger(app);
  
  // Or setup Swagger with authentication
  // swaggerService.setupSwaggerWithAuth(app);
  
  await app.listen(3000);
}
bootstrap();

3. Override configuration programmatically (optional)

import { SwaggerConfig } from '@bvhoach2393/nest-swagger';

const customConfig: SwaggerConfig = {
  title: 'Custom API Title',
  description: 'Custom API Description',
  version: '2.0.0',
  path: 'docs',
  apiDocPath: 'api-json',
  tag: 'custom'
};

swaggerService.setupSwagger(app, customConfig);

Important Notes

⚠️ ConfigService is Optional: The library can work without ConfigService. If ConfigService is not available, it will use default values or the configuration you provide manually.

• With ConfigService: Reads environment variables automatically
• Without ConfigService: Uses default values and shows a warning

Usage Options

Option 1: With ConfigModule (Recommended)

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { NestSwaggerModule } from '@bvhoach2393/nest-swagger';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    NestSwaggerModule,
  ],
})
export class AppModule {}

Option 2: Without ConfigModule

import { Module } from '@nestjs/common';
import { NestSwaggerModule } from '@bvhoach2393/nest-swagger';

@Module({
  imports: [NestSwaggerModule],
})
export class AppModule {}

In this case, you should provide configuration manually:

const customConfig: SwaggerConfig = {
  title: 'My API',
  description: 'API Description',
  version: '1.0.0',
  path: 'api-docs',
  apiDocPath: 'api-json',
  tag: 'api'
};

swaggerService.setupSwagger(app, customConfig);

API Reference

NestSwaggerService

Methods

setupSwagger(app: INestApplication, config?: SwaggerConfig): void

Sets up basic Swagger documentation for your NestJS application.

Parameters:

• app - NestJS application instance
• config - Optional configuration to override environment variables

setupSwaggerWithAuth(app: INestApplication, config?: SwaggerConfig): void

Sets up Swagger documentation with Bearer authentication support.

Parameters:

• app - NestJS application instance
• config - Optional configuration to override environment variables

SwaggerConfig Interface

interface SwaggerConfig {
  title?: string;           // API title
  description?: string;     // API description
  version?: string;         // API version
  path?: string;           // Swagger UI path
  apiDocPath?: string;     // JSON documentation path
  tag?: string;            // Default API tag
}

Running Tests

Unit Tests

npm run test

Test Coverage

npm run test:cov

Test Watch Mode

npm run test:watch

Building the Library

npm run build

Publishing to NPM Registry

1. Build the library

npm run build

2. Test the package locally

npm pack

3. Login to NPM (if not already logged in)

npm login

4. Publish to NPM

npm publish

5. Publish with specific tag (optional)

npm publish --tag beta

Development

Prerequisites

• Node.js >= 16.0.0
• npm >= 7.0.0

Setup Development Environment

1. Clone the repository
2. Install dependencies: npm install
3. Run tests: npm run test
4. Build the library: npm run build

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Author

bvhoach2393

• Email: [email protected]
• GitHub: @bvhoach2393

4. Copy files to dist and publish

npm run publish:lib:swagger

### Version Management

```bash
# Patch version (1.0.0 -> 1.0.1)
npm version patch

# Minor version (1.0.0 -> 1.1.0)
npm version minor

# Major version (1.0.0 -> 2.0.0)
npm version major

Examples

Basic Example

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { NestSwaggerService } from '@bvhoach2393/nest-swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const swaggerService = new NestSwaggerService();
  swaggerService.setupSwagger(app);
  
  await app.listen(3000);
  console.log('API Documentation available at: http://localhost:3000/api');
}
bootstrap();

Advanced Example with Authentication

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { NestSwaggerService } from '@bvhoach2393/nest-swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const swaggerService = new NestSwaggerService();
  
  swaggerService.setupSwaggerWithAuth(app, {
    title: 'My Secure API',
    description: 'API with Bearer Token and API Key authentication',
    version: '2.0',
    path: 'docs',
    tag: 'secure-api'
  });
  
  await app.listen(3000);
  console.log('API Documentation available at: http://localhost:3000/docs');
}
bootstrap();

Dependencies

Runtime Dependencies

• @nestjs/swagger: ^8.0.0
• swagger-ui-express: ^5.0.0

Peer Dependencies

• @nestjs/common: ^10.0.0 || ^11.0.0
• @nestjs/core: ^10.0.0 || ^11.0.0
• reflect-metadata: ^0.1.13 || ^0.2.0

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.