OpenAPI (v3) specification schema as pydantic class
Project description
openapi-schema-pydantic
OpenAPI (v3) specification schema as Pydantic classes.
The naming of the classes follows the schema in OpenAPI specification.
Installation
pip install openapi-schema-pydantic
Try me
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.0.3",
"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, 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")}}
)
},
})
Use Pydantic classes as schema
- The Schema Object in OpenAPI has definitions and tweaks in JSON Schema, which is hard to comprehend and define a good data class
- Pydantic already has a good way to create JSON schema, let's not re-invent the wheel
The approach to deal with this:
- Use
PydanticSchema
objects to represent theSchema
inOpenAPI
object - Invoke
construct_open_api_with_schema_class
to resolve the JSON schemas and references
from 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.0.3",
"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.json() / OpenAPI.dict()
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.0.3 | here |
Non-pydantic schema types
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.0.3 | here |
License
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for openapi-schema-pydantic-1.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | c036bf6d2f02854372b2b7b3ba7cbeec3ccca115822b148916a616b2d9541447 |
|
MD5 | 28ed10abf7bcbc17f92b654615f3dabc |
|
BLAKE2b-256 | 3f73dcd975dfad51c3dfb134638fca9ede31bdf27a8bbb9b9f7e7ac320f16fba |
Hashes for openapi_schema_pydantic-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 42c857c5138ff4c04a15f59e4e40bef280afb5994002be023df07707e8465098 |
|
MD5 | f9c507430226b962bb77b58e1fbb51b2 |
|
BLAKE2b-256 | b002a91dd72050048ebc5ef8b28a3269b3b7d66ddce3702183af260455b602ca |