OpenAPI Parser

Parse OpenAPI 3 documents into fully typed Python dataclass objects. Navigate your API specification programmatically — servers, paths, operations, parameters, schemas, security schemes, and more.

Version	Status
2.0	Deprecated
3.0	Supported
3.1	In development

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: {}
""")

Navigate servers, paths, and operations

specification = parse("swagger.yml")

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

# List all paths and their HTTP methods
for path in specification.paths:
    methods = ", ".join(op.method.value for op in path.operations)
    print(f"{path.url}: [{methods}]")

# Inspect operation details
for path in specification.paths:
    for op in path.operations:
        print(f"[{op.method.value}] {path.url}: {op.summary}")
        if op.deprecated:
            print("  (deprecated)")
        if op.operation_id:
            print(f"  operationId: {op.operation_id}")

Enum strictness

By default, content types, string formats, and other enum fields are validated against predefined enums. For specs that use custom values, pass strict_enum=False:

# Accepts non-standard content types like "application/vnd.api+json"
spec = parse("swagger.yml", strict_enum=False)

When strict mode is off, unrecognized values are wrapped in a LooseEnum object instead of raising an error.

Error Handling

from openapi_parser.errors import ParserError

try:
    spec = parse("invalid.yml")
except ParserError as e:
    print(f"Parsing failed: {e}")

Data Model

Parsed documents return a Specification object composed of fully typed dataclasses:

Model	Description
Specification	Root document — version, info, servers, paths, schemas, security
Info	API metadata — title, version, description, contact, license
Server	Server definition — url, description, variables
Path	URL path — operations, parameters
Operation	HTTP method — responses, parameters, request body, security
Parameter	Path/query/header/cookie param — schema, style, required
Response	Status code, description, content, headers
RequestBody	Content, description, required
Content	Media type, schema, example
Schema	Base type — Integer, Number, String, Boolean, Array, Object, Null
Property	Object property — name, schema
OneOf/AnyOf	Composition schemas with discriminator support
Security	Security scheme — apiKey, http, oauth2, openIdConnect
OAuthFlow	OAuth flow — authorization, token, scopes
Header	Response header — name, schema, description
Tag	Tag with optional external docs
ExternalDoc	External documentation reference
Discriminator	Polymorphism discriminator — property name, mapping

See the specification module for all available fields and types.

Development

# Install with dev dependencies
uv sync --dev

# Lint
uv run ruff check .
uv run mypy .
uv run ty check .

# Test
uv run pytest

# Format
uv run ruff format .