OpenAPI 缺少 FastAPI 应用程序中某些 Pydantic 模型的模式

Answer 1

FastAPI 将为用作Request Body 或Response Model 的模型生成模式。当声明query_args: FaultQueryParams = Depends()（使用Depends）时，你的端点不会期望request body，而是query参数；因此，FaultQueryParams 不会包含在 OpenAPI 文档的架构中。

要添加其他架构，您可以extend/modify the OpenAPI schema。下面给出了示例（确保在定义所有路由之后添加用于修改架构的代码，即在代码末尾）。

class FaultQueryParams(BaseModel):
    f_id: Optional[int] = Field(None, description="id for the host", example=12345, title="Fault ID")
    hostname: Optional[str]
    status: Literal["open", "closed", "all"] = Field("open")
    ...
    
@app.post('/predict')
def predict(query_args: FaultQueryParams = Depends()):
    return query_args

def get_extra_schemas():
    return {
              "FaultQueryParams": {
                "title": "FaultQueryParams",
                "type": "object",
                "properties": {
                  "f_id": {
                    "title": "Fault ID",
                    "type": "integer",
                    "description": "id for the host",
                    "example": 12345
                  },
                  "hostname": {
                    "title": "Hostname",
                    "type": "string"
                  },
                  "status": {
                    "title": "Status",
                    "enum": [
                      "open",
                      "closed",
                      "all"
                    ],
                    "type": "string",
                    "default": "open"
                  },
                   ...
                }
              }
            }

from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="FastAPI",
        version="1.0.0",
        description="This is a custom OpenAPI schema",
        routes=app.routes,
    )
    new_schemas = openapi_schema["components"]["schemas"]
    new_schemas.update(get_extra_schemas())
    openapi_schema["components"]["schemas"] = new_schemas
    
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

一些有用的说明

注1

无需手动为要添加到文档中的额外模型键入架构，您可以让 FastAPI 为您执行此操作，方法是使用该模型向您的代码添加一个端点（您随后将在获取架构后将其删除）作为请求体或响应模型，例如：

@app.post('/predict') 
def predict(query_args: FaultQueryParams):
    return query_args

然后，您可以在http://127.0.0.1:8000/openapi.json 获取生成的 JSON 模式，如documentation 中所述。从那里，您可以将模型的模式复制并粘贴到您的代码中并直接使用它（如上面的 get_extra_schema() 方法所示）或将其保存到文件并从文件中加载 JSON 数据，如下所示：

import json
...

new_schemas = openapi_schema["components"]["schemas"]

with open('extra_schemas.json') as f:    
    extra_schemas = json.load(f)
    
new_schemas.update(extra_schemas)   
openapi_schema["components"]["schemas"] = new_schemas

...

笔记2

对于declare metadata，例如description、example等，对于您的查询参数，您应该使用Query而不是Field来定义您的参数，并且由于您不能使用Pydantic模型做到这一点，所以您可以声明一个custom dependency class，描述为here，如下所示：

from fastapi import FastAPI, Query, Depends
from typing import Optional

class FaultQueryParams:
    def __init__(
        self,
        f_id: Optional[int] = Query(None, description="id for the host", example=12345)

    ):
        self.f_id = f_id

app = FastAPI()

@app.post('/predict')
def predict(query_args: FaultQueryParams = Depends()):
    return query_args

上面可以用@dataclass装饰器重写，如下图：

from fastapi import FastAPI, Query, Depends
from typing import Optional
from dataclasses import dataclass

@dataclass
class FaultQueryParams:
        f_id: Optional[int] = Query(None, description="id for the host", example=12345)

app = FastAPI()

@app.post('/predict')
def predict(query_args: FaultQueryParams = Depends()):
    return query_args

Answer 2

感谢@Chris 提供的指针，最终导致我使用dataclasses 批量定义查询参数，它工作得很好。

@dataclass
class FaultQueryParams1:
    f_id: Optional[int] = Query(None, description="id for the host", example=55555)
    hostname: Optional[str] = Query(None, example="test-host1.domain.com")
    status: Literal["open", "closed", "all"] = Query(
        None, description="fetch open/closed or all records", example="all"
    )
    created_by: Optional[str] = Query(
        None,
        description="fetch records created by particular user",
        example="user-id",
    )