filter-openapi-json-spec 📝

A powerful 🚀 CLI tool to filter OpenAPI specifications (formerly Swagger) based on various criteria. This tool exclusively processes JSON-formatted OpenAPI specifications for both input and output. Perfect for generating client-specific API documentation or reducing large specs to only what's relevant.

✨ Features

• Path Filtering: Include or exclude API paths based on regular expressions.
• Tag Filtering: Keep only operations associated with specific tags.
• Method Filtering: Filter operations by HTTP methods (GET, POST, PUT, DELETE, etc.).
• Component Filtering: Automatically include only referenced schemas, responses, parameters, etc.
• Output Format: Outputs filtered specifications in JSON format.

📦 Installation

You can install filter-openapi-json-spec globally using npm:

npm install -g filter-openapi-json-spec

🚀 Usage

The filter-openapi-json-spec command takes an input JSON OpenAPI spec file and outputs a filtered JSON version.

filter-openapi-json-spec [options]

Options

• --path <path>: Exact path to filter (e.g., "/users/{id}")
• --paths <paths>: Comma-separated list of exact paths
• --filter <pattern>: Pattern to filter by (default: path matching)
• --by <method>: Filter method: path, operationId, tag (default: path)
• --tag <tag>: Filter by tag name
• --input <file>: Input OpenAPI spec file (default: ./docs.json)
• --output <file>: Output file path (default: filtered-openapi.json)
• --dry-run: Preview without writing output file
• --stats: Show detailed statistics
• --help: Show this help message

Examples

1. Filter a single endpoint (dry-run)

filter-openapi-json-spec --path "/users/{id}" --dry-run

2. Filter multiple endpoints

filter-openapi-json-spec --paths "/users,/auth/login" --output api-subset.json

3. Filter by pattern

filter-openapi-json-spec --filter "bin_collection" --output filtered.json

4. Filter by tag

filter-openapi-json-spec --tag "Authentication" --output auth-api.json

5. Filter by operationId

filter-openapi-json-spec --filter "getUser" --by operationId --output user-api.json

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

📄 License

This project is licensed under the ISC License. See the LICENSE file for details.