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.
| Version | Status |
|---|---|
| 2.0 | Supported* |
| 3.0 | Supported |
| 3.1 | Supported |
| 3.2 | Supported |
* 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:
| Model | Description |
|---|---|
Specification |
Root document — openapi, info, servers, paths, components, security |
Info |
API metadata — title, version, description, contact, license |
Server |
Server definition — url, description, variables |
PathItem |
URL path — get/post/put/delete/patch, parameters, servers |
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 |
MediaType |
Media type — schema, example, encoding |
Schema |
Data definition — type, properties, items, composition |
Components |
Reusable schemas, responses, parameters, examples, headers, ... |
SecurityScheme |
Security scheme — apiKey, http, oauth2, openIdConnect, mutualTLS |
OAuthFlow |
OAuth flow — authorization, token, scopes |
Header |
Response header — name, schema, description |
Link |
Link definition — operation, parameters, request body |
Example |
Example — value, summary, externalValue |
Tag |
Tag with optional external docs |
ExternalDoc |
External documentation reference |
Discriminator |
Polymorphism discriminator — property name, mapping |
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/
1 maintainer
Metadata
1 maintainer
Release files for openapi3-parser 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| openapi3_parser-2.0.0.tar.gz | 14.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| openapi3_parser-2.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 32.4 kB
Release files / openapi3_parser-2.0.0.tar.gz
| Download URL | openapi3_parser-2.0.0.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3ad834fbc5dd1d63f50424a0fcf9b73bf69fac6cd060e42399b79221daa9042c
|
|
BLAKE2b-256 checksum How to use checksums |
e8cfe7367dd3e34558a298103f793fa61aae7480c5d5c1b1e8735df76f897ecc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / openapi3_parser-2.0.0-py3-none-any.whl
| Download URL | openapi3_parser-2.0.0-py3-none-any.whl |
|---|---|
| Size | 18.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9b3f2b7a8d91acf6afef231479339538578bb9421fb425ecf049bd2494e27395
|
|
BLAKE2b-256 checksum How to use checksums |
dfd26ee69c41a55f1f4d8a56932ccdfff07bed01173faac1cc666ba7f264019c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
