openapi-pydantic

Modern, type-safe OpenAPI schemas in Python using Pydantic 1.8+ and 2.x

Table of Contents

• Table of Contents
• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 📝 Usage Examples
• 🧑‍💻 Using Pydantic Classes as Schema
• Notes
  • Use of OpenAPI.model_dump() / OpenAPI.model_dump_json() / OpenAPI.json() / OpenAPI.dict()
  • Non-pydantic schema types
  • Use OpenAPI 3.0 instead of 3.1
  • Pydantic version compatibility
• 🙏 Credits
• 📄 License

✨ Features

• Supports both Pydantic 1.8+ and 2.x
• Supports the OpenAPI 3.1 specification (with 3.0 also available)
• Easy construction of OpenAPI schemas using Python objects or dicts
• Seamless integration with Pydantic models for request/response schemas
• Utility functions for schema conversion and validation

📦 Installation

pip install openapi-pydantic

🚀 Quick Start

from openapi_pydantic import OpenAPI, Info, PathItem, Operation, Response

open_api = OpenAPI(
    info=Info(
        title="My own API",
        version="v0.0.1",
    ),
    paths={
        "/ping": PathItem(
            get=Operation(
                responses={
                    "200": Response(
                        description="pong"
                    )
                }
            )
        )
    },
)
# For Pydantic 1.x, use `json` instead of `model_dump_json`
print(open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2))

{
  "openapi": "3.1.1",
  "info": {
    "title": "My own API",
    "version": "v0.0.1"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/ping": {
      "get": {
        "responses": {
          "200": {
            "description": "pong"
          }
        },
        "deprecated": false
      }
    }
  }
}

📝 Usage Examples

Pydantic allows you to use object, dict, or mixed data for input. The following examples all produce the same OpenAPI result as above:

from openapi_pydantic import parse_obj, OpenAPI, PathItem, Response

# Construct OpenAPI from dict, inferring the correct schema version
open_api = parse_obj({
    "openapi": "3.1.1",
    "info": {"title": "My own API", "version": "v0.0.1"},
    "paths": {
        "/ping": {
            "get": {"responses": {"200": {"description": "pong"}}}
        }
    },
})

# Construct OpenAPI v3.1 schema from dict
# For Pydantic 1.x, use `parse_obj` instead of `model_validate`
open_api = OpenAPI.model_validate({
    "info": {"title": "My own API", "version": "v0.0.1"},
    "paths": {
        "/ping": {
            "get": {"responses": {"200": {"description": "pong"}}}
        }
    },
})

# Construct OpenAPI with mix of dict/object
open_api = OpenAPI.model_validate({
    "info": {"title": "My own API", "version": "v0.0.1"},
    "paths": {
        "/ping": PathItem(
            get={"responses": {"200": Response(description="pong")}}
        )
    },
})

🧑‍💻 Using Pydantic Classes as Schema

💡 Tip: Use your own Pydantic models for request/response schemas and let openapi-pydantic handle the conversion!

from pydantic import BaseModel, Field
from openapi_pydantic import OpenAPI
from openapi_pydantic.util import PydanticSchema, construct_open_api_with_schema_class

def construct_base_open_api() -> OpenAPI:
    # For Pydantic 1.x, use `parse_obj` instead of `model_validate`
    return OpenAPI.model_validate({
        "info": {"title": "My own API", "version": "v0.0.1"},
        "paths": {
            "/ping": {
                "post": {
                    "requestBody": {"content": {"application/json": {
                        "schema": PydanticSchema(schema_class=PingRequest)
                    }}},
                    "responses": {"200": {
                        "description": "pong",
                        "content": {"application/json": {
                            "schema": PydanticSchema(schema_class=PingResponse)
                        }},
                    }},
                }
            }
        },
    })

class PingRequest(BaseModel):
    """Ping Request"""
    req_foo: str = Field(description="foo value of the request")
    req_bar: str = Field(description="bar value of the request")

class PingResponse(BaseModel):
    """Ping response"""
    resp_foo: str = Field(description="foo value of the response")
    resp_bar: str = Field(description="bar value of the response")

open_api = construct_base_open_api()
open_api = construct_open_api_with_schema_class(open_api)

# print the result openapi.json
# For Pydantic 1.x, use `json` instead of `model_dump_json`
print(open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2))

{
  "openapi": "3.1.1",
  "info": {
    "title": "My own API",
    "version": "v0.0.1"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/ping": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PingRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "pong",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PingResponse"
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "components": {
    "schemas": {
      "PingRequest": {
        "title": "PingRequest",
        "required": [
          "req_foo",
          "req_bar"
        ],
        "type": "object",
        "properties": {
          "req_foo": {
            "title": "Req Foo",
            "type": "string",
            "description": "foo value of the request"
          },
          "req_bar": {
            "title": "Req Bar",
            "type": "string",
            "description": "bar value of the request"
          }
        },
        "description": "Ping Request"
      },
      "PingResponse": {
        "title": "PingResponse",
        "required": [
          "resp_foo",
          "resp_bar"
        ],
        "type": "object",
        "properties": {
          "resp_foo": {
            "title": "Resp Foo",
            "type": "string",
            "description": "foo value of the response"
          },
          "resp_bar": {
            "title": "Resp Bar",
            "type": "string",
            "description": "bar value of the response"
          }
        },
        "description": "Ping response"
      }
    }
  }
}

Notes

Use of OpenAPI.model_dump() / OpenAPI.model_dump_json() / OpenAPI.json() / OpenAPI.dict()

⚠️ Important: Always use by_alias=True, exclude_none=True when dumping models to JSON or dict, to ensure OpenAPI compatibility.

# OK (Pydantic 2)
open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2)
# OK (Pydantic 1)
open_api.json(by_alias=True, exclude_none=True, indent=2)

# Not good
open_api.model_dump_json(indent=2)
open_api.json(indent=2)

More info about field aliases:

Non-pydantic schema types

Some schema types are not implemented as pydantic classes. See:

Use OpenAPI 3.0 instead of 3.1

ℹ️ Some UI renderings (e.g. Swagger) do not support OpenAPI 3.1.x. You can use 3.0.x by importing from different paths:

from openapi_pydantic.v3.v3_0 import OpenAPI, ...
from openapi_pydantic.v3.v3_0.util import PydanticSchema, construct_open_api_with_schema_class

Pydantic version compatibility

Compatibility with both major versions of Pydantic (1.8+ and 2.*) is achieved using a module called compat.py. It detects the installed version and exports version-specific symbols for use by the rest of the package. The compat.py module is not intended to be imported by other packages, but may serve as an example for supporting multiple Pydantic versions.

🙏 Credits

This library is based on the original implementation by Kuimono of OpenAPI Schema Pydantic, which is no longer actively maintained.

📄 License

MIT License