# openapi-pydantic

> Pydantic OpenAPI schema implementation

- **URL**: https://www.freshcrate.ai/projects/openapi-pydantic
- **Author**: Mike Oakley
- **Category**: Frameworks
- **Latest version**: `0.5.1` (2026-04-21)
- **License**: MIT
- **Source**: https://github.com/mike-oakley/openapi-pydantic
- **Language**: Python
- **GitHub**: 118 stars, 23 forks
- **Registry**: pypi (`openapi-pydantic`)
- **Tags**: `openapi`, `parser`, `pydantic`, `pypi`, `schema`, `validation`

## Description

# openapi-pydantic

[![PyPI](https://img.shields.io/pypi/v/openapi-pydantic)](https://pypi.org/project/openapi-pydantic/)
[![PyPI - License](https://img.shields.io/pypi/l/openapi-pydantic)](https://github.com/mike-oakley/openapi-pydantic/blob/main/LICENSE)

OpenAPI schema implemented in [Pydantic](https://github.com/samuelcolvin/pydantic). Both Pydantic 1.8+ and 2.x are supported.

The naming of the classes follows the schema in 
[OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.1.md#schema).

> This library is forked from [OpenAPI Schema Pydantic](https://github.com/kuimono/openapi-schema-pydantic)  (at version [1.2.4](https://github.com/kuimono/openapi-schema-pydantic/releases/tag/v1.2.4)) which is no longer actively maintained.

## Installation

`pip install openapi-pydantic`

## Try me

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

# Construct OpenAPI by pydantic objects
open_api = OpenAPI(
    info=Info(
        title="My own API",
        version="v0.0.1",
    ),
    paths={
        "/ping": PathItem(
            get=Operation(
                responses={
                    "200": Response(
                        description="pong"
                    )
                }
            )
        )
    },
)
# Note: for Pydantic 1.x, replace `model_dump_json` with `json`
print(open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2))
```

Result:

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

## Take advantage of Pydantic

Pydantic is a great tool. It allows you to use object / dict / mixed data for input.

The following examples give the same OpenAPI result as above:

```python
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
# Note: for Pydantic 1.x, replace `model_validate` with `parse_obj`
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
# Note: for Pydantic 1.x, replace `model_validate` with `parse_obj`
open_api = OpenAPI.model_validate({
    "info": {"title": "My own API", "version": "v0.0.1"},
    "paths": {
        "/ping": PathItem(
            get={"responses": {"200": Response(description="pong")}}
        )
    },
})
```

## Use Pydantic classes as schema

- The [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.4.md#schemaObject)
  in OpenAPI has definitions and tweaks in JSON Schema, which are hard to comprehend and define a good data class
- Pydantic already has a good way to [create JSON schema](https://pydantic-docs.helpmanual.io/usage/schema/).
  Let's not reinvent the wheel.

The approach to deal with this:

1. Use `PydanticSchema` objects to represent the `Schema` in `OpenAPI` object
2. Invoke `construct_open_api_with_schema_class` to resolve the JSON schemas and references

```python
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:
    # Note: for Pydantic 1.x, replace `model_validate` with `parse_obj`
    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_ope

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `0.5.1` | 2026-04-21 | Low | Imported from PyPI (0.5.1) |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |
| `v0.5.1` | 2025-01-08 | Low | <!-- Release notes generated using configuration in .github/release.yml at main -->  ## What's Changed ### Fixed 🐛 * fix: Correct schema test assertion after Pydantic update. by @mike-oakley in https://github.com/mike-oakley/openapi-pydantic/pull/52 * fix: replace invalid characters in $ref field with underscore. by @jfschneider in https://github.com/mike-oakley/openapi-pydantic/pull/50  ## New Contributors * @jfschneider made their first contribution in https://github.com/mike-oakley/o |

## Citation

- HTML: https://www.freshcrate.ai/projects/openapi-pydantic
- Markdown: https://www.freshcrate.ai/projects/openapi-pydantic.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/openapi-pydantic/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._