[](LICENSE)
## 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:
```bash
cargo install --path .
```
Make sure `~/.cargo/bin` is in your `PATH` so you can run the tool from anywhere:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
## Usage
Extract specific paths and methods from an OpenAPI spec:
```bash
openapi-subset --input api.yaml --output subset.yaml --path /pets --method GET
```
Use a regular expression to match multiple paths:
```bash
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:
```bash
openapi-subset --input api.yaml --output subset.yaml --path /pets --path /stores --method GET
```
Filter paths by regex and methods together:
```bash
openapi-subset --input api.yaml --output subset.yaml --path-regex "^/users/\\d+$" --method POST
```
Keep all paths but prune components by filtering methods only:
```bash
openapi-subset --input api.yaml --output subset.yaml --method DELETE
```
See `openapi-subset --help` for all options.
## Rebuilding
After making changes, rebuild the tool:
```bash
cargo build --release
```
Or reinstall:
```bash
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:
```bash
cargo test
```
Tests will fail if any changes break existing functionality, helping ensure the tool remains reliable.