openapi-normalizer

Load, resolve, and normalise OpenAPI 3.x and Swagger 2.0 specifications into a single, version-agnostic data model.

• 🔗 $ref resolution — resolves intra-document references with cycle protection
• 📦 Version normalisation — OpenAPI 3.x and Swagger 2.0 become the same internal model
• 🌐 HTTP + local files — load specs from URLs or filesystem paths
• 📄 JSON + YAML — both formats supported
• ✅ Typed, tested, and linted

Installation

pip install openapi-normalizer

Requires Python 3.10+.

Quickstart

from openapi_normalizer import load_spec, resolve_refs, parse_spec

# Load from URL or file (JSON or YAML)
document = load_spec("https://petstore3.swagger.io/api/v3/openapi.json")

# Resolve all intra-document $ref pointers
document = resolve_refs(document)

# Normalise into a version-agnostic model
spec = parse_spec(document)

print(spec.title)     # "Swagger Petstore - OpenAPI 3.0"
print(spec.base_url)  # "/api/v3"
for op in spec.operations:
    print(op.method, op.path, op.operation_id)

API

load_spec(ref, *, timeout=30.0) → dict

Load a spec from a URL or local file. Returns the parsed document as a dict.

resolve_refs(document) → dict

Resolve all local $ref pointers (e.g. #/components/schemas/Pet) in-place. External references are preserved. Cycles are broken safely.

detect_version(document) → str

Return "openapi-3" or "swagger-2".

parse_spec(document, *, source_ref=None, base_url_override=None) → ParsedSpec

Normalise a ref-resolved document into a ParsedSpec containing:

• title, base_url, spec_version
• operations — list of Operation (method, path, parameters, request body, tags)
• security_schemes — dict of SecurityScheme (type, scheme, name, location)

License

MIT