# 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