Lib.rs

Project Description

Ever wanted to share only a small part of your massive 100+ endpoint API without dumping the whole spec?
openapi-subset is a command-line tool that extracts exactly the endpoints and HTTP methods you care about from an OpenAPI (Swagger) specification, and automatically prunes unused components — giving you a clean, minimal spec to share or document.

Key features:

• Subset by specific paths or HTTP methods, or use regex to match multiple endpoints.
• Automatically prunes unused components (schemas, responses, parameters, etc.) for you.
• Generates a minimal, focused OpenAPI spec tailored to your needs — perfect for sharing or documentation.

Installation

Build and install locally using Cargo:

cargo install --path .

Make sure ~/.cargo/bin is in your PATH so you can run the tool from anywhere:

export PATH="$HOME/.cargo/bin:$PATH"

Usage

Extract specific paths and methods from an OpenAPI spec:

openapi-subset --input api.yaml --output subset.yaml --path /pets --method GET

Use a regular expression to match multiple paths:

openapi-subset --input api.yaml --output subset.yaml --path-regex "^/users/\\d+$"

You can use the --path, --path-regex, and --method flags individually or in combination to precisely control which parts of the OpenAPI spec are included in the output.

• --path selects specific API paths by exact match. You can specify this flag multiple times to include multiple paths.
• --path-regex selects API paths matching a regular expression.
• --method filters the HTTP methods (e.g., GET, POST) within the selected paths.

When combined, the tool extracts only the specified methods within the selected paths or path patterns.

Examples

Extract multiple specific paths:

openapi-subset --input api.yaml --output subset.yaml --path /pets --path /stores --method GET

Filter paths by regex and methods together:

openapi-subset --input api.yaml --output subset.yaml --path-regex "^/users/\\d+$" --method POST

Keep all paths but prune components by filtering methods only:

openapi-subset --input api.yaml --output subset.yaml --method DELETE

See openapi-subset --help for all options.

Rebuilding

After making changes, rebuild the tool:

cargo build --release

Or reinstall:

cargo install --path .

Contributing

1. Fork the repository and clone it.
2. Create a new branch for your changes.
3. Commit your changes with a descriptive message.
4. Push the branch to your fork.
5. Open a pull request.

Running Tests

This repository includes integration tests that use the Petstore OpenAPI example to validate path and method filtering as well as component pruning. To run the tests, use:

cargo test

Tests will fail if any changes break existing functionality, helping ensure the tool remains reliable.