NestJS Swagger Sync

A NestJS module that automatically synchronizes your Swagger/OpenAPI documentation with Postman collections. This module provides seamless integration between your API documentation and Postman, making it easier to maintain up-to-date API collections.

Features

• 🔄 Automatic synchronization of Swagger/OpenAPI docs to Postman collections
• 🧪 Optional test running before synchronization
• 🔍 Automatic detection and updating of existing collections
• 📁 Hierarchical organization of API endpoints
• 🔐 Environment variable support for baseUrl and authentication
• 📝 Detailed logging of the sync process
• ⚡ Support for all NestJS versions (6.x and above)

Prerequisites

Before you begin, ensure you have:

• Node.js (>= 12.0.0)
• NestJS (>= 7.0.0)
• A Postman account and API key
• Swagger/OpenAPI documentation set up in your NestJS application

Installation

• NPM

npm install nestjs-swagger-sync

• YARN

yarn add nestjs-swagger-sync

Quick Start

1. Import the module in your app.module.ts:

import { Module } from '@nestjs/common';
import { SwaggerSyncModule } from 'nestjs-swagger-sync';

@Module({
  imports: [
    SwaggerSyncModule.register({
      apiKey: 'your-postman-api-key',
      swaggerPath: 'api',
      baseUrl: 'http://localhost:3000',
      collectionName: 'My API Collection',
      runTest: true,
      ignorePathWithBearerToken: ['api/auth/login'],
    }),
  ],
})
export class AppModule {}

2. Use the service in your controller or service:

import { Controller, Post } from '@nestjs/common';
import { SwaggerSyncService } from 'nestjs-swagger-sync';

@Controller()
export class AppController {
  constructor(private readonly swaggerSyncService: SwaggerSyncService) {}

  @Post('sync')
  async syncSwagger() {
    await this.swaggerSyncService.syncSwagger();
    return { message: 'Swagger documentation synced with Postman' };
  }
}

Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | apiKey | string | Yes | - | Your Postman API key | | swaggerPath | string | Yes | swagger | The path to the Swagger documentation | | baseUrl | string | Yes | - | The base URL of your API | | collectionName | string | No | API Collection | Override the Name of swagger to Postman collection. Defaults to swwager Title or API Collection | | runTest | boolean | No | false | Whether to run Newman tests before uploading | | ignorePathWithBearerToken | array | No | [] | Array of paths to ignore when adding a Bearer token to the request |

Postman API Key

To get your Postman API key:

1. Log in to Postman
2. Go to your workspace settings
3. Navigate to the "API Keys" section
4. Create a new API key with appropriate permissions

Environment Variables

The module supports the following environment variables:

POSTMAN_API_KEY=your-api-key
API_BASE_URL=http://localhost:3000

Usage Examples

Basic Usage

SwaggerSyncModule.register({
  apiKey: process.env.POSTMAN_API_KEY,
})

With Custom Configuration

SwaggerSyncModule.register({
    apiKey: 'your-postman-api-key',
    swaggerPath: 'api',
    baseUrl: 'http://localhost:3000',
    collectionName: 'My API Collection',
    runTest: true,
    ignorePathWithBearerToken: ['api/auth/login'],
})

Manual Sync Trigger

@Injectable()
export class YourService {
  constructor(private readonly swaggerSyncService: SwaggerSyncService) {}

  async updatePostmanCollection() {
    try {
      await this.swaggerSyncService.syncSwagger();
      console.log('Postman collection updated successfully');
    } catch (error) {
      console.error('Failed to update Postman collection:', error);
    }
  }
}

Authentication Handling

The module automatically adds authentication headers to requests:

• Excludes auth headers with ignoreVariablesPathWithBearerToken
• Adds Bearer {{token}} auth header for all other endpoints
• Supports environment variables for flexible token management

Error Handling

The module provides detailed error messages for common issues:

• Invalid Postman API key
• API server not running
• Network connectivity issues
• Invalid Swagger documentation format

Compatibility

This package is compatible with:

• NestJS versions 7.x and above
• Node.js version 12 and above
• TypeScript 4.x and above

Tested with:

• NestJS 7.x
• NestJS 8.x
• NestJS 9.x
• NestJS 10.x

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

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

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:cov

# Run tests in watch mode
npm run test:watch

Building

# Build the package
npm run build

# Format code
npm run format

# Lint code
npm run lint

License

This project is licensed under the MIT License.

Support

For support, please:

1. Check the GitHub Issues page
2. Create a new issue if your problem isn't already listed
3. Contact the maintainers

Acknowledgments

• NestJS team for the amazing framework
• Postman team for their API platform
• All contributors who help improve this package

Author

• Garseta Yusuf