SpringBoot2Postman

Generate Postman collections automatically from any Spring Boot project — with or without OpenAPI/Swagger.

Features

• Dual Strategy Support: Works with OpenAPI specs (JSON/YAML) or directly parses Java source code
• Static Analysis: No compilation required — parses @RestController annotations directly
• Spring Boot Aware: Understands @GetMapping, @PostMapping, @RequestParam, @PathVariable, etc.
• Type Resolution: Automatically converts Java types to JSON Schema
• Flexible Input: Accepts project paths, file paths, or OpenAPI URLs
• Large Codebase Support: Parallel processing with configurable concurrency
• Package Filtering: Include/exclude patterns for targeting specific packages

Installation

npm install -g @springtools/springboot2postman

Or use directly with npx:

npx @springtools/springboot2postman --project ./my-spring-app

Quick Start

# From a Spring Boot project directory
springboot2postman --project . --out api.postman_collection.json

# From an OpenAPI URL
springboot2postman --project https://api.example.com/v3/api-docs --out api.json

# With a custom base URL
springboot2postman --project ./my-app --base-url https://staging.example.com

# Large project with filtering
springboot2postman --project ./large-app --include "com.example.api.*" --exclude "*Test*" --concurrency 10

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --project <path> | Project path or OpenAPI URL (required) | — | | --out <file> | Output file path | ./postman_collection.json | | --base-url <url> | Override the base URL in the collection | — | | --format <format> | Output format: postman or openapi | postman | | --include <patterns> | Include only matching packages (comma-separated globs) | — | | --exclude <patterns> | Exclude matching packages (comma-separated globs) | — | | --concurrency <n> | Max parallel file parsing | 5 | | --verbose | Enable verbose logging | false |

How It Works

Strategy Detection

The tool automatically detects the best approach:

1. URL Input → Fetches and converts OpenAPI spec
2. OpenAPI File Found → Uses OpenAPI strategy (looks for openapi.json, swagger.yaml, etc.)
3. Java Controllers Found → Uses Parser strategy (static analysis)

Parser Strategy

When no OpenAPI spec is available, the tool:

1. Scans for files with @RestController or @Controller annotations
2. Applies include/exclude filters
3. Parses controllers in parallel (configurable concurrency)
4. Extracts endpoint mappings (@GetMapping, @PostMapping, etc.)
5. Resolves parameter annotations (@PathVariable, @RequestParam, @RequestBody)
6. Converts Java types to JSON Schema
7. Builds an OpenAPI specification
8. Converts to Postman collection format

Supported Annotations

| Controller | Method | Parameter | |------------|--------|-----------| | @RestController | @GetMapping | @PathVariable | | @Controller | @PostMapping | @RequestParam | | @RequestMapping | @PutMapping | @RequestBody | | | @DeleteMapping | @RequestHeader | | | @PatchMapping | |

Error Codes

| Code | Description | |------|-------------| | PROJECT_NOT_FOUND | The specified project path does not exist | | NO_CONTROLLERS_FOUND | No Spring Boot controllers found in the project | | OPENAPI_FETCH_FAILED | Failed to fetch OpenAPI specification from URL/file | | INVALID_OPENAPI | The OpenAPI specification is invalid or unsupported | | PARSE_ERROR | Failed to parse a Java file | | CONVERSION_FAILED | Failed to convert to Postman collection |

Requirements

• Node.js 16.0.0 or higher
• npm 7.0.0 or higher