在 swagger 文档中显示变量的描述或注释

Question

我正在使用 post 方法创建一个函数并 class 它。

由于我使用了FastAPI，它会自动生成swagger文档页面，我可以在那里看到功能描述或示例数据。

我的class和功能如下，

from pydantic import BaseModel, Field
from typing import Optional, List


@app.post("/user/item")
def func1(args1: User, args2: Item):
    ...


class User(BaseModel):
    name: str
    state: List[str]

    class Config:
        schema_extra = {
            "example": {
                "name": "Mike",
                "state": ["Texas", "Arizona"]
            }
        }


    class Item(BaseModel):
        _id: int = Field(..., example=3, description="item id")

通过Field中的schema_extra和example属性，可以看到函数描述Request body中的示例值

好像

{
   "args1": {
        "name": "Mike",
        "state": ["Texas", "Arizona"]     # state user visits. <-- I'd like to add this here or in other place.
    },
    "args2: {
        "_id": 3   <-- Here I can't description 'item id'
    }
}

不过，我想在 example value 中添加说明或评论，例如上面的#state user visits。

我尝试添加 pydantic Field 的 description 属性，但我认为它只显示 get 方法的参数。

有什么办法吗？任何帮助将不胜感激。

Answer 1

您正试图在将发送到服务器的实际 JSON 负载中传递“注释”。因此，这种方法行不通。在字段中添加description的方法如下图。 Users/you 可以查看 descriptions/comments 以及提供的示例，方法是在“模式”（底部例如，在 http://127.0.0.1:8000/docs 访问 OpenAPI 时。或者，通过单击“示例值”旁边的“模式”，位于“请求正文”中给出的示例上方。

class User(BaseModel):
    name: str = Field(..., description="Add user name")
    state: List[str]  = Field(..., description="State user visits")

    class Config:
        schema_extra = {
            "example": {
                "name": "Mike",
                "state": ["Texas", "Arizona"]
            }
        }

或者，您可以在端点中使用 Body 字段，允许您添加在“请求正文”中的示例下方显示的描述。根据 documentation:

But when you use example or examples with any of the other utilities (Query(), Body(), etc.) those examples are not added to the JSON Schema that describes that data (not even to OpenAPI's own version of JSON Schema), they are added directly to the path operation declaration in OpenAPI (outside the parts of OpenAPI that use JSON Schema).

您可以添加多个示例（及其相关描述），如 documentation 中所述。下面的示例：

@app.post("/user/item")
async def update_item(
    user: User = Body(
        ...,
        examples={
            "normal": {
                "summary": "A normal example",
                "description": "**name**: Add user name.  **state**: State user vistis. ",
                "value": {
                    "name": "Mike",
                    "state": ["Texas", "Arizona"]
                },
            }
        }
    ),
):
    return {"user": user}

在 swagger 文档中显示变量的描述或注释

Show description or comments for variables in swagger docs

pydantic

fastapi