Description

# openapi-pydantic [](https://pypi.org/project/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