OpenAPI (v3) specification schema as pydantic class
OpenAPI (v3) specification schema as Pydantic classes.
The naming of the classes follows the schema in OpenAPI specification.
pip install openapi-schema-pydantic
from openapi_schema_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"
)
}
)
)
},
)
print(open_api.json(by_alias=True, exclude_none=True, indent=2))
Result:
{
"openapi": "3.1.0",
"info": {
"title": "My own API",
"version": "v0.0.1"
},
"servers": [
{
"url": "/"
}
],
"paths": {
"/ping": {
"get": {
"responses": {
"200": {
"description": "pong"
}
},
"deprecated": false
}
}
}
}
Pydantic is a great tool, allow you to use object / dict / mixed data for for input.
The following examples give the same OpenAPI result as above:
from openapi_schema_pydantic import OpenAPI, PathItem, Response
# Construct OpenAPI from dict
open_api = OpenAPI.parse_obj({
"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.parse_obj({
"info": {"title": "My own API", "version": "v0.0.1"},
"paths": {
"/ping": PathItem(
get={"responses": {"200": Response(description="pong")}}
)
},
})
The approach to deal with this:
PydanticSchema
objects to represent the Schema
in OpenAPI
objectconstruct_open_api_with_schema_class
to resolve the JSON schemas and referencesfrom pydantic import BaseModel, Field
from openapi_schema_pydantic import OpenAPI
from openapi_schema_pydantic.util import PydanticSchema, construct_open_api_with_schema_class
def construct_base_open_api() -> OpenAPI:
return OpenAPI.parse_obj({
"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
print(open_api.json(by_alias=True, exclude_none=True, indent=2))
Result:
{
"openapi": "3.1.0",
"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"
}
}
}
}
When using OpenAPI.json()
/ OpenAPI.dict()
function,
arguments by_alias=True, exclude_none=True
has to be in place.
Otherwise the result json will not fit the OpenAPI standard.
# OK
open_api.json(by_alias=True, exclude_none=True, indent=2)
# Not good
open_api.json(indent=2)
More info about field alias:
OpenAPI version | Field alias info |
---|---|
3.1.0 | here |
3.0.3 | here |
Some schema types are not implemented as pydantic classes. Please refer to the following for more info:
OpenAPI version | Non-pydantic schema type info |
---|---|
3.1.0 | here |
3.0.3 | here |
Some UI renderings (e.g. Swagger) still do not support OpenAPI 3.1.0. It is allowed to use the old 3.0.3 version by importing from different paths:
from openapi_schema_pydantic.v3.v3_0_3 import OpenAPI, ...
from openapi_schema_pydantic.v3.v3_0_3.util import PydanticSchema, construct_open_api_with_schema_class