如何使用 FastAPI 记录 OpenAPI/Swagger 中的默认 None/null？

问题描述：

使用 ORM，我想要发出一个 POST 请求，让一些字段具有一个null值，该值将在数据库中转换为那里指定的默认值。

问题是 OpenAPI（Swagger）文档忽略了默认值，并且仍然默认None提示。UUID

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional
from uuid import UUID
import uvicorn


class Table(BaseModel):
    # ID: Optional[UUID]      # the docs show a example UUID, ok
    ID: Optional[UUID] = None # the docs still shows a uuid, when it should show a null or valid None value.

app = FastAPI()  
    
@app.post("/table/", response_model=Table)
def create_table(table: Table):
    # here we call to sqlalchey orm etc.
    return 'nothing important, the important thing is in the docs'
    
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

在文档中的 OpenAPI 模式示例（请求正文）中，我们发现：

{
 "ID": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

这不行，因为我指定的默认值是None，所以我期望的是这个：

{
 "ID": null, # null is the equivalent of None here
}

它将把一个传递null给ID并最终在数据库中解析为默认值（即新生成的UUID）。

解决方案 1：

声明Optional参数时，用户不应null在用或（在 Python 中）指定的请求中包含这些参数None，以便None。默认情况下，此类参数的值将为None，除非用户在发送请求时指定其他值。

因此，您所要做的就是使用和example为 Pydantic 模型声明一个自定义，如文档中所述，如下所示。以下示例将在 OpenAPI（Swagger UI）中创建一个空的（即）请求主体，可以成功提交（因为这是模型的唯一属性并且是可选的）。Config`schema_extra{}ID`

class Table(BaseModel):
    ID: Optional[UUID] = None
    
    class Config:
        schema_extra = {
            "example": {
            }
        }

@app.post("/table/", response_model=Table)
def create_table(table: Table):
    return table

如果Table模型包含一些其他必需的属性，您可以example为这些属性添加值，如下所示：

class Table(BaseModel):
    ID: Optional[UUID] = None
    some_attr: str
    
    class Config:
        schema_extra = {
            "example": {
                "some_attr": "Foo"
            }
        }

如果您想要保留除属性之外的其余属性的自动生成示例，则可以使用以下命令从生成的架构中的模型属性中删除（受架构定制的启发）：IDID

class Table(BaseModel):
    ID: Optional[UUID] = None
    some_attr: str
    some_attr2: float
    some_attr3: bool
    
    class Config:
        @staticmethod
        def schema_extra(schema: Dict[str, Any], model: Type['Table']) -> None:
            del schema.get('properties')['ID']

此外，如果您想example为某些属性添加自定义功能，您可以使用Field()（如此处所述）；例如，some_attr: str = Field(example="Foo")。

另一个可能的解决方案是修改生成的 OpenAPI 模式，如此答案的解决方案 3 中所述。不过，上述解决方案可能更适合这种情况。

笔记

ID: Optional[UUID] = None与 相同ID: UUID = None。如之前在 FastAPI 网站中所述（另请参阅此答案）：

FastAPI 不使用Optional Optional[str]，但它可以让你编辑器为你提供更好的支持并检测错误。

从那时起，FastAPI对其文档进行了如下修改：

UnionUnion[str, None]将允许你的编辑器为你提供更好的支持并检测错误。

因此，与 和 相同。ID: Union[UUID, None] = None在Python 3.10+中，还可以使用（参见此处）。ID: Optional[UUID] = None`ID: UUID = None`ID: UUID| None = None

根据FastAPI 文档（请参阅Info所提供链接中的部分）：

请记住，使参数可选的最重要的部分是：

= None

或：

= Query(default=None)

因为它将使用它None作为默认值，这样就使得该参数不再是必需的。

该Union[str, None]部分允许您的编辑器提供更好的支持，但这并不是告诉 FastAPI 此参数不是必需的。