OpenAPI Parser

Parse OpenAPI and Swagger documents into fully typed Pydantic models. Navigate your API specification programmatically — servers, paths, operations, parameters, schemas, security schemes, and more.

* Swagger 2.0 documents are normalized to OpenAPI 3.0.

Installation

pip install openapi3-parser

Quick Start

from openapi_parser import parse

specification = parse("swagger.yml")
print(specification.info.title)  # e.g. "User example service"

Use Cases

Parse from different sources

# From file path
spec = parse("specs/openapi.yml")

# From URL
spec = parse("https://example.com/openapi.json")

# From raw string
spec = parse(spec_string="""
openapi: "3.0.0"
info:
  title: My API
  version: "1.0.0"
paths: {}
""")

# From raw string with external $refs (resolved relative to base_uri)
spec = parse(
    spec_string=open("specs/openapi.yml").read(),
    base_uri="file:///abs/path/specs/openapi.yml",
)

Navigate servers, paths, and operations

specification = parse("swagger.yml")

# List all servers
for server in specification.servers:
    print(f"{server.description} - {server.url}")

# Iterate paths and their HTTP methods
for path, path_item in specification.paths.items():
    methods = ", ".join(
        method for method in ("get", "put", "post", "delete", "patch")
        if getattr(path_item, method) is not None
    )
    print(f"{path}: [{methods}]")

# Inspect operation details
for path_item in specification.paths.values():
    get_op = path_item.get
    if get_op is None:
        continue
    print(f"[GET] {path}: {get_op.summary}")
    if get_op.deprecated:
        print("  (deprecated)")
    if get_op.operation_id:
        print(f"  operationId: {get_op.operation_id}")

Follow $ref references

$ref entries are resolved in place and annotated with a ref_name pointing back to their canonical location:

schema = specification.components.schemas["Pet"]
print(schema.ref_name)  # "#/components/schemas/Pet"

Error Handling

from openapi_parser.errors import ParserError

try:
    spec = parse("invalid.yml")
except ParserError as e:
    print(f"Parsing failed: {e}")
    for detail in e.errors():
        print(detail["loc"], detail["msg"])

Data Model

Parsed documents return a Specification object composed of fully typed Pydantic models:

See the models package for all available fields and types.

Development

# Install with dev dependencies
uv sync --dev

# Lint
uv run ruff check src/ tests/
uv run mypy src/ tests/
uv run ty check

# Test
uv run pytest

# Format
uv run ruff format src/ tests/