Pydantic OpenAPI Schema Implementation

0.5.1 · active · verified Sun Mar 29

openapi-pydantic provides a type-safe and modern implementation of OpenAPI schemas using Pydantic models, currently at version 0.5.1. It facilitates the generation of OpenAPI documents by defining API structures with Python classes, and is actively maintained with updates to support new OpenAPI and Pydantic versions.

Warnings

breaking Version 0.5.0 introduced significant changes to the internal structure, particularly for supporting multiple OpenAPI specification versions (3.0.4 and 3.1.1). Import paths for specific OpenAPI versions, such as `v3_0`, were adjusted. This might break existing code that used hardcoded version imports.
Fix: Review your import statements. For OpenAPI 3.1.1 (default), import directly from `openapi_pydantic`. For OpenAPI 3.0.x, use `from openapi_pydantic.v3.v3_0 import OpenAPI, ...`.
breaking Version 0.4.0 included a fix to ensure `Header` objects generate valid OpenAPI specifications. While a 'fix', if your application relied on or processed the previously invalid output, this change could alter behavior or break downstream consumers of your generated spec.
Fix: Test your generated OpenAPI documents and any consuming clients after upgrading to ensure compatibility with the now-valid `Header` object definitions.
gotcha The library supports both Pydantic v1 (1.8+) and v2. However, there are API differences between Pydantic versions. For instance, Pydantic v1 uses `.json()` for serialization, while Pydantic v2 uses `.model_dump_json()`. Similarly, `parse_obj` (v1) and `model_validate` (v2) have different usages.
Fix: When writing code that needs to be compatible with both Pydantic versions or when migrating, be mindful of these method name changes. Use `model_dump_json()` and `model_validate()` for Pydantic v2, or check `pydantic.VERSION` for conditional logic if strict compatibility is required.
gotcha While `openapi-pydantic` supports OpenAPI 3.1.1 by default, some older UI rendering tools (e.g., specific versions of Swagger UI) may not fully support OpenAPI 3.1.x. If you encounter rendering issues with your generated spec, it might be due to tool compatibility.
Fix: If experiencing rendering issues, consider explicitly generating an OpenAPI 3.0.x spec by importing from `openapi_pydantic.v3.v3_0` and specifying the version in the `OpenAPI` object's `openapi` field. Alternatively, ensure your rendering tool is updated to a version that supports OpenAPI 3.1.x.

Install

pip install openapi-pydantic Install latest version

Imports

OpenAPI
```
from openapi_pydantic import OpenAPI
```
For the latest OpenAPI 3.1.1 (default), import directly. For OpenAPI 3.0.x, use `from openapi_pydantic.v3.v3_0 import OpenAPI` due to structural changes in v0.5.0 to accommodate different OAS versions.
Info
```
from openapi_pydantic import Info
```
PathItem
```
from openapi_pydantic import PathItem
```
Operation
```
from openapi_pydantic import Operation
```
Response
```
from openapi_pydantic import Response
```

Quickstart

This quickstart demonstrates how to create a basic OpenAPI document by defining an `OpenAPI` object, including `Info`, `PathItem`, `Operation`, and `Response` objects. It also shows how to integrate a custom Pydantic `BaseModel` (`Item`) into the OpenAPI schema components, leveraging Pydantic's `model_json_schema()` for automatic schema generation. The final output is a JSON string representing the OpenAPI specification.

from openapi_pydantic import OpenAPI, Info, PathItem, Operation, Response
from pydantic import BaseModel, Field # Ensure pydantic is installed

# Define a simple Pydantic model for a schema component
class Item(BaseModel):
    id: int = Field(..., description="Unique ID of the item")
    name: str = Field(..., description="Name of the item")

# Construct OpenAPI object using imported classes
open_api = OpenAPI(
    info=Info(
        title="My Awesome API",
        version="v1.0.0",
        description="A simple API generated with openapi-pydantic."
    ),
    paths={
        "/items": PathItem(
            get=Operation(
                summary="Retrieve all items",
                responses={
                    "200": Response(
                        description="A list of items",
                        content={
                            "application/json": {
                                "schema": {"type": "array", "items": {"$ref": "#/components/schemas/Item"}}
                            }
                        }
                    )
                }
            )
        )
    },
    components={
        "schemas": {
            "Item": Item.model_json_schema() # Use Pydantic's schema generation
        }
    }
)

# For Pydantic v2, use model_dump_json. For Pydantic v1, use .json()
print(open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2))

view raw JSON →