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