この記事に書いてあること
- 今すぐpydantic v2 + fastapi v100を使うため、アドホックにOAS3.0.xなopenapi.jsonを吐けるようにする話
この記事に書いてないこと
- pydantic v2の変更点
- JSON SchemaとOASの細かいバージョン差異
前置き
ついにpydantic v2がリリースされました!
パフォーマンスの向上も勿論ですが、それ以外にもrequiredとnullableの関係が整理されたり, namespaceが整理されたりと、便利な変更が盛り沢山です。
fastapiも早速v2対応をしたv0.100をリリースしているので、さて移行するぞ!と、行きたいところなのですがここで問題があります。
JSON SchemaとOpenAPIの差分に関する問題です。
ざっくりOASとJSON Schemaの差分について整理すると
- おそらく一番メジャーなopenapi code generatorであるopenapi-generatorはOAS3.0までしか対応していない(generatorの種類も多いしOAS3.1対応はまだかかりそう…)
- OAS3.0.xはJSON Schema Draft 5(JSON Schema Specification Wright Draft 00)のサブセットを使っている
- pydantic v1ではJSON Schema Draft 7を採用していたが、pydantic v2ではJSON Schema Draft 2020-12をターゲットにしている
- OAS3.1はJSON Schema Draft 2020-12準拠になる
ということで、要はpydantic v2の吐くschemaはOAS3.1でないと読めないという問題が発生します。
本題
手元で触っていて困ったのは
- Literalがv1ではstringのenumだったが、v2ではconstになる
- T | Noneがv1ではtype: T + nullable: trueだったが、v2ではanyof[{ type: T }, { type: null }]になる
の2点です
1は
class A(BaseModel):
a: Literal['a']
がv1では
{"title": "A", "type": "object", "properties": {"a": {"title": "A", "enum": ["a"], "type": "string"}}, "required": ["a"]}
からv2では
{"properties": {"a": {"const": "a", "title": "A"}}, "required": ["a"], "title": "A", "type": "object"}
になるという問題です
2は
class B(BaseModel):
b: int | None
がv1では
{"title": "B", "type": "object", "properties": {"b": {"title": "B", "type": "integer"}}}
からv2では
{"properties": {"b": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "B"}}, "required": ["b"], "title": "B", "type": "object"}
になります。
アドホックな解決策
ということで上記スキーマをv2の方からv1の方に変換するためにFastAPI.openapiを無理矢理上書きします。
from typing import Any, Callable
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
def _override_schema(schema: dict[str, Any]) -> dict[str, Any]:
new_schema = schema
if next((x for x in schema.get("anyOf", []) if x.get("type", None) == "null"), None) and len(schema.get("anyOf", [])) == 2:
new_schema = {
**next((x for x in schema["anyOf"] if x.get("type", None) != "null")),
"nullable": True,
}
if schema.get("title", None):
new_schema["title"] = schema["title"]
schema = new_schema
elif schema.get("const", None) is not None:
new_schema = {
"type": "string",
"enum": [schema["const"]],
}
if schema.get("title", None):
new_schema["title"] = schema["title"]
schema = new_schema
else:
schema = new_schema
return schema
def _override_openapi_schema(openapi_schema: dict[str, Any]) -> dict[str, Any]:
for key in openapi_schema["components"]["schemas"]:
openapi_schema["components"]["schemas"][key]["properties"] = {
key: _override_schema(value) for key, value in openapi_schema["components"]["schemas"][key]["properties"].items()
}
for path in openapi_schema["paths"]:
for method in openapi_schema["paths"][path]:
if openapi_schema["paths"][path][method].get("parameters", None):
openapi_schema["paths"][path][method]["parameters"] = [
{
**parameter,
"schema": _override_schema(parameter["schema"]),
} for parameter in openapi_schema["paths"][path][method]["parameters"]
]
return openapi_schema
app = FastAPI(title="app_name", version="app_version")
def gen_openapi() -> dict[str, Any]:
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="app_name",
version="app_version",
routes=app.routes,
openapi_version="3.0.2",
)
app.openapi_schema = _override_openapi_schema(openapi_schema)
return app.openapi_schema
app.openapi = gen_openapi
というような感じで、上記2つの問題を無理矢理変換することでOASv3.0まで対応のcode generatorでもpydantic v2 + fastapi v0.100を使うことができるようになります。
手元で詰まったのはこの2点のみでしたが、仕様上は他にも変換するべき項目があると思うので(OASが対応していないkeywordはこの辺参照)、見つけたら是非教えてください。