如何使用FastAPI在OpenAPI/Swagger中记录缺省None/null？

Question

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

问题是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）。

Answer 1

当您声明可选参数时，用户不必在其请求中包含这些参数（用null值指定）才能成为null。参数的默认值将是null，除非用户在发送请求时指定其他值。

因此，您所要做的就是使用< code>Config和< code>schema_extra为Pydantic模型声明一个自定义的< code >示例，如文档中所述，如下所示。下面的示例将在OpenAPI (Swagger UI)中创建一个空的(即< code>{})请求体，该请求体可以成功提交(因为< code>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

如果表模型包含一些其他必需属性，则可以为这些属性添加示例值，如下所示：

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

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

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']

此外，如果您想将自定义示例添加到某些属性中，您可以使用字段（）（如下所述）；例如，some_attr： str=字段（示例="Foo"）。

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

< code>ID:可选[UUID] =无与< code>ID: UUID =无相同。如之前在FastAPI网站中记录的那样(参见此答案):

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

从那时起，FastAPI 修改了他们的文档，内容如下：

< code>Union[str，None]中的联合将允许您的编辑器为您提供更好的支持并检测错误。

因此，ID：Union[UUID，无]=无与ID：可选[UUID]=无和ID：UUID=无相同。在Python 3.10中，也可以使用ID：UUID|无=无。

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

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

= None

或：

= Query(default=None)

因为它将使用＜code＞None＜/code＞作为默认值，这样就不需要参数。

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