fastapi之api文档参数示例

177 阅读2分钟

持续创作,加速成长!这是我参与「掘金日新计划 · 6 月更文挑战」的第16天,点击查看活动详情

  • 有的时候我们希望自己写的openapi文档尽可能的详细清楚,比如对参数有详细的示例。
  • 这包括:请求体参数、查询参数、路径参数等等都有详尽的示例介绍。
  • 幸运的是fastapi为我们提供了多种添加示例的方式,并且使用灵活简单。

schema_extra

  • 使用 Configschema_extra 为Pydantic模型类声明一个示例
  • 这些示例都用于openapi文档的显示。
 from typing import Union
 ​
 from fastapi import FastAPI
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
 ​
     class Config:
         schema_extra = {
             "example": {
                 "name": "Foo",
                 "description": "A very nice Item",
                 "price": 35.4,
                 "tax": 3.2,
             }
         }
 ​
 ​
 @app.put("/items/{item_id}")
 async def update_item(item_id: int, item: Item):
     results = {"item_id": item_id, "item": item}
     return results

example

  • Field, Path, Query, Body等函数中使用 example
  • 传递的example参数不会添加任何验证,只会添加注释,用于文档的目的。
 from typing import Union
 ​
 from fastapi import FastAPI
 from pydantic import BaseModel, Field
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str = Field(example="Foo")
     description: Union[str, None] = Field(default=None, example="A very nice Item")
     price: float = Field(example=35.4)
     tax: Union[float, None] = Field(default=None, example=3.2)
 ​
 ​
 @app.put("/items/{item_id}")
 async def update_item(item_id: int, item: Item):
     results = {"item_id": item_id, "item": item}
     return results
  • 在Body中使用example,比如给请求体提供一个示例。
 from typing import Union
 ​
 from fastapi import Body, FastAPI
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
 ​
 ​
 @app.put("/items/{item_id}")
 async def update_item(
     item_id: int,
     item: Item = Body(
         example={
             "name": "Foo",
             "description": "A very nice Item",
             "price": 35.4,
             "tax": 3.2,
         },
     ),
 ):
     results = {"item_id": item_id, "item": item}
     return results

examples

  • 也可以使用examples为参数提供多个示例,除此之外,Query和Path中也可以用相同的用法。
 from typing import Union
 ​
 from fastapi import Body, FastAPI
 from pydantic import BaseModel
 ​
 app = FastAPI()
 ​
 ​
 class Item(BaseModel):
     name: str
     description: Union[str, None] = None
     price: float
     tax: Union[float, None] = None
 ​
 ​
 @app.put("/items/{item_id}")
 async def update_item(
     *,
     item_id: int,
     item: Item = Body(
         examples={
             "normal": {
                 "summary": "A normal example",
                 "description": "A **normal** item works correctly.",
                 "value": {
                     "name": "Foo",
                     "description": "A very nice Item",
                     "price": 35.4,
                     "tax": 3.2,
                 },
             },
             "converted": {
                 "summary": "An example with converted data",
                 "description": "FastAPI can convert price `strings` to actual `numbers` automatically",
                 "value": {
                     "name": "Bar",
                     "price": "35.4",
                 },
             },
             "invalid": {
                 "summary": "Invalid data is rejected with an error",
                 "value": {
                     "name": "Baz",
                     "price": "thirty five point four",
                 },
             },
         },
     ),
 ):
     results = {"item_id": item_id, "item": item}
     return results