OpenAPI Pydantic

OpenAPI Pydantic is a library of Pydantic models that represent the OpenAPI specification, letting you build, validate, and parse OpenAPI 3.1 (and 3.0) documents as ordinary typed Python objects. Every part of the spec, from the root document down to schemas, paths, and components, is a Pydantic model, so your editor autocompletes fields and invalid documents fail validation instead of silently misbehaving.

It supports both Pydantic 1.8+ and 2.x, round-trips documents to and from JSON, and can even derive OpenAPI schema objects from your existing Pydantic data models. That makes it a solid foundation for code generators, API tooling, and anything that needs to programmatically produce or consume OpenAPI definitions with full type safety.

What You Get

• Pydantic models covering the full OpenAPI 3.1 specification, with 3.0 also available
• Support for both Pydantic 1.8+ and 2.x from a single package
• Validated construction of OpenAPI documents that rejects malformed specs
• Parsing of existing OpenAPI JSON into typed Python objects
• Helpers to derive OpenAPI schema objects from your own Pydantic data models

Common Use Cases

• Programmatically generating OpenAPI documents in a typed, validated way
• Parsing and inspecting third-party OpenAPI specs in Python tooling
• Building API code generators or documentation pipelines on a solid schema model

Under The Hood

Architecture The package mirrors the OpenAPI specification as a hierarchy of Pydantic BaseModel subclasses under the openapi_pydantic package, with the root OpenAPI model composing Info, Paths, Components, Schema, and the rest. A compatibility layer detects the installed Pydantic major version and adapts field configuration and serialization accordingly, and a separate module exposes the 3.0 variant of the models.

Tech Stack Pure Python with Pydantic as the only core runtime dependency, packaged with pyproject.toml and managed via uv. It deliberately supports the full Pydantic 1.8+ through 2.x range, using version-aware shims rather than pinning to one line.

Code Quality The repository has a focused test suite (18 test files) covering parsing, aliases, config examples, and schema classes, with coverage reporting wired into CI. The models are declarative and consistent, which keeps behavior predictable across Pydantic versions.

API Design Usage feels like ordinary Pydantic: instantiate OpenAPI(...), use model_validate to parse and model_dump_json to serialize. Field names track the spec closely with sensible aliasing, so anyone who knows OpenAPI can build documents with almost no learning curve.