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

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

Use Cases

Parse from different sources

# From file pathspec=parse("specs/openapi.yml")
# From URLspec=parse("https://example.com/openapi.json")
# From raw stringspec=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 serversforserverinspecification.servers:
print(f"{server.description} - {server.url}")
# List all paths and their HTTP methodsforpathinspecification.paths:
methods=", ".join(op.method.valueforopinpath.operations)
print(f"{path.url}: [{methods}]")
# Inspect operation detailsforpathinspecification.paths:
foropinpath.operations:
print(f"[{op.method.value}] {path.url}: {op.summary}")
ifop.deprecated:
print(" (deprecated)")
ifop.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

fromopenapi_parser.errorsimportParserErrortry:
spec=parse("invalid.yml")
exceptParserErrorase:
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 .