nestjs-to-collection

🚀 Transform NestJS endpoints into Postman and Insomnia collections via CLI.

Features

• 📄 Swagger/OpenAPI Support: Generate collections from your existing Swagger specification
• 🔍 Decorator Scanning: Automatically extract endpoints from NestJS decorators
• 📮 Postman Export: Generate Postman Collection v2.1 format
• 🦋 Insomnia Export: Generate Insomnia Collection v4 format
• 🎯 Interactive CLI: User-friendly prompts for easy configuration
• ⚡ Programmatic API: Use as a library in your code

Installation

# Global installation (recommended for CLI usage)
npm install -g nestjs-to-collection

# Local installation (for programmatic usage)
npm install nestjs-to-collection

Requirements

• Node.js >= 20.0.0
• NestJS >= 10.0.0 (peer dependency)
• @nestjs/swagger >= 7.0.0 (optional, for Swagger support)

CLI Usage

Interactive Mode

The easiest way to use the tool is through interactive mode:

nest-to-collection generate -i
# or using the short alias
ntc generate -i

This will guide you through the following options:

1. Source type (Swagger or Decorators)
2. Path to swagger.json or source folder
3. Output format (Postman or Insomnia)
4. Collection name
5. Base URL
6. Output file path

Command Line Options

nest-to-collection generate [options]

Options:
  -s, --source <type>        Source type: swagger or decorators (default: "swagger")
  -o, --output <format>      Output format: postman or insomnia (default: "postman")
  -p, --swagger-path <path>  Path to swagger.json file
  -d, --src-path <path>      Path to NestJS src folder (default: "./src")
  -out, --output-path <path> Output file path (default: "./collection")
  -b, --base-url <url>       Base URL for API (default: "{{baseUrl}}")
  -n, --name <name>          Collection name
  -i, --interactive          Run in interactive mode

Examples

Generate from Swagger (Postman)

ntc generate -s swagger -p ./swagger.json -o postman -n "My API" -out ./my-api

Generate from Swagger (Insomnia)

ntc generate -s swagger -p ./swagger.json -o insomnia -n "My API" -out ./my-api

Generate from Decorators (Postman)

ntc generate -s decorators -d ./src -o postman -n "My API" -out ./my-api

Generate from Decorators (Insomnia)

ntc generate -s decorators -d ./src -o insomnia -n "My API" -out ./my-api

Save Configuration

You can save your configuration for future use:

ntc init

This creates a nest-to-collection.config.json file in your project root.

Programmatic Usage

Using with Swagger

import { SwaggerParser, PostmanGenerator, InsomniaGenerator } from 'nestjs-to-collection';

// Parse Swagger file
const parser = new SwaggerParser();
const collection = await parser.parse('./swagger.json');

// Generate Postman collection
const postmanGenerator = new PostmanGenerator();
const postmanJson = postmanGenerator.generate(collection);

// Generate Insomnia collection
const insomniaGenerator = new InsomniaGenerator();
const insomniaJson = insomniaGenerator.generate(collection);

// Save to files
fs.writeFileSync('collection.postman_collection.json', postmanJson);
fs.writeFileSync('collection.insomnia_collection.json', insomniaJson);

Using with NestJS Decorators

import { DecoratorParser, PostmanGenerator } from 'nestjs-to-collection';

// Parse NestJS source files
const parser = new DecoratorParser();
const collection = await parser.parse('./src');

// Customize collection
collection.name = 'My Custom API';
collection.baseUrl = 'https://api.example.com';

// Generate Postman collection
const generator = new PostmanGenerator();
const json = generator.generate(collection);

Parse from Swagger URL

import { SwaggerParser, PostmanGenerator } from 'nestjs-to-collection';

const parser = new SwaggerParser();
const collection = await parser.parseFromUrl('https://api.example.com/swagger.json');

const generator = new PostmanGenerator();
const json = generator.generate(collection);

Supported NestJS Decorators

The decorator parser supports the following NestJS decorators:

HTTP Method Decorators

• @Get()
• @Post()
• @Put()
• @Patch()
• @Delete()
• @Options()
• @Head()

Parameter Decorators

• @Param()
• @Query()
• @Body()
• @Headers()

Swagger Decorators (from @nestjs/swagger)

• @ApiTags()
• @ApiOperation()
• @ApiParam()
• @ApiQuery()
• @ApiBody()
• @ApiResponse()

Output Formats

Postman Collection v2.1

The generated Postman collection includes:

• Organized folder structure based on controllers/tags
• Request body examples
• Query parameters
• Path parameters
• Headers
• Collection variables (baseUrl)
• Response examples

Insomnia Collection v4

The generated Insomnia collection includes:

• Workspace with organized request groups
• Environment variables
• Request body with proper MIME types
• Query parameters
• Path parameters (Insomnia format)
• Headers

Generating Swagger from NestJS

If you don't have a swagger.json file yet, you can generate one from your NestJS application:

1. Install @nestjs/swagger

npm install @nestjs/swagger

2. Configure Swagger in main.ts

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
import * as fs from 'fs';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API description')
    .setVersion('1.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Save swagger.json to file
  fs.writeFileSync('./swagger.json', JSON.stringify(document, null, 2));

  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

3. Run your application

npm run start

This will generate a swagger.json file that you can use with this tool.

API Reference

Types

interface ApiCollection {
  name: string;
  description?: string;
  version?: string;
  baseUrl?: string;
  groups: ApiGroup[];
  variables?: CollectionVariable[];
}

interface ApiGroup {
  name: string;
  description?: string;
  endpoints: ApiEndpoint[];
}

interface ApiEndpoint {
  path: string;
  method: HttpMethod;
  summary?: string;
  description?: string;
  operationId?: string;
  tags?: string[];
  parameters?: ApiParameter[];
  requestBody?: ApiRequestBody;
  responses?: Record<string, ApiResponse>;
}

Classes

SwaggerParser

• parse(filePath: string): Promise<ApiCollection> - Parse from file
• parseFromUrl(url: string): Promise<ApiCollection> - Parse from URL
• parseFromObject(swagger: SwaggerDocument): ApiCollection - Parse from object

DecoratorParser

• parse(srcPath: string): Promise<ApiCollection> - Parse NestJS source files

PostmanGenerator

• generate(collection: ApiCollection): string - Generate Postman JSON

InsomniaGenerator

• generate(collection: ApiCollection): string - Generate Insomnia JSON

Contributing

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

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.

Support

If you find this package helpful, please consider giving it a ⭐ on GitHub!

For bugs and feature requests, please open an issue.