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/
Metadata
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 | Provenance | Actions |
|---|---|---|---|---|
| openapi3_parser-2.0.0.tar.gz | 14.4 kB | Without provenance | Details for openapi3_parser-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openapi3_parser-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for openapi3_parser-2.0.0-py3-none-any.whl |
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}
|
Security for openapi3-parser 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.