cc789d3b32
- Parse and validate OpenAPI 3.x / Swagger 2.0 specs - Query endpoints by method, path pattern, tag, operationId - Get component schema details - Generate TypeScript interfaces from schemas - Support local files and remote URLs Tools: parse-spec, validate-spec, query-endpoints, get-schema, generate-types Co-Authored-By: Claude <noreply@anthropic.com>
85 lines
2.2 KiB
Markdown
85 lines
2.2 KiB
Markdown
# OpenAPI Spec Tools
|
|
|
|
Parse, validate, and explore OpenAPI/Swagger specifications.
|
|
|
|
## Arguments
|
|
|
|
- `$ARGUMENTS` - Subcommand and arguments
|
|
|
|
## Subcommands
|
|
|
|
### parse <file>
|
|
Parse an OpenAPI spec and show overview (version, paths, schemas, servers).
|
|
|
|
### validate <file>
|
|
Validate a spec against OpenAPI schema. Reports errors and warnings.
|
|
|
|
### endpoints <file> [--method METHOD] [--path PATTERN] [--tag TAG]
|
|
List API endpoints. Optional filters:
|
|
- `--method GET|POST|PUT|DELETE|...` - Filter by HTTP method
|
|
- `--path /users.*` - Filter by path regex pattern
|
|
- `--tag users` - Filter by tag name
|
|
|
|
### schema <file> <name>
|
|
Get details of a component schema by name.
|
|
|
|
### types <file> [schema1 schema2 ...]
|
|
Generate TypeScript interfaces from schemas. Optionally specify schema names.
|
|
|
|
## Execution
|
|
|
|
Based on the subcommand in `$ARGUMENTS`, use the appropriate MCP tool:
|
|
|
|
### If subcommand is "parse":
|
|
Use the `mcp__swagger-tools__parse-spec` tool with the file path.
|
|
|
|
### If subcommand is "validate":
|
|
Use the `mcp__swagger-tools__validate-spec` tool with the file path.
|
|
|
|
### If subcommand is "endpoints":
|
|
Use the `mcp__swagger-tools__query-endpoints` tool with:
|
|
- `path`: The spec file path
|
|
- `method`: Value after `--method` (if provided)
|
|
- `pathPattern`: Value after `--path` (if provided)
|
|
- `tag`: Value after `--tag` (if provided)
|
|
|
|
### If subcommand is "schema":
|
|
Use the `mcp__swagger-tools__get-schema` tool with:
|
|
- `path`: The spec file path
|
|
- `schemaName`: The schema name argument
|
|
|
|
### If subcommand is "types":
|
|
Use the `mcp__swagger-tools__generate-types` tool with:
|
|
- `path`: The spec file path
|
|
- `schemas`: Array of schema names (if any specified after the file)
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Parse and show overview
|
|
/openapi parse api.yaml
|
|
|
|
# Validate spec
|
|
/openapi validate openapi.json
|
|
|
|
# List all GET endpoints
|
|
/openapi endpoints api.yaml --method GET
|
|
|
|
# List endpoints matching /users path
|
|
/openapi endpoints api.yaml --path /users
|
|
|
|
# Get User schema details
|
|
/openapi schema api.yaml User
|
|
|
|
# Generate all TypeScript types
|
|
/openapi types api.yaml
|
|
|
|
# Generate specific schemas only
|
|
/openapi types api.yaml User Pet Order
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Supports OpenAPI 3.0, 3.1, and Swagger 2.0 specifications
|
|
- Files can be YAML or JSON format
|
|
- References ($ref) are automatically dereferenced
|