FastApi（5）声明请求示例数据额外数据类型

作者学习fastapi文档时整理欢迎各位查看十一、声明请求示例数据你可以为你的应用将接收的数据声明示例。这里有几种实现方式。1、Pydantic 模型中的额外 JSON Schema 数据你可以为一个 Pydantic 模型声明examples它们会被添加到生成的 JSON Schema 中。fromfastapiimportFastAPIfrompydanticimportBaseModel appFastAPI()classItem(BaseModel):name:strdescription:str|NoneNoneprice:floattax:float|NoneNonemodel_config{json_schema_extra:{examples:[{name:Foo,description:A very nice Item,price:35.4,tax:3.2,}]}}app.put(/items/{item_id})asyncdefupdate_item(item_id:int,item:Item):results{item_id:item_id,item:item}returnresults这些额外信息会原样添加到该模型输出的JSON Schema中并会在 API 文档中使用。你可以使用属性model_config它接收一个dict你可以设置json_schema_extra其值为一个dict包含你希望出现在生成 JSON Schema 中的任意附加数据包括examples。提示你也可以用同样的技巧扩展 JSON Schema添加你自己的自定义额外信息。例如你可以用它为前端用户界面添加元数据等。注意OpenAPI 3.1.0自 FastAPI 0.99.0 起使用增加了对examples的支持它是JSON Schema标准的一部分。在此之前只支持使用单个示例的关键字example。OpenAPI 3.1.0 仍然支持它但它已被弃用并不属于 JSON Schema 标准。因此建议你把example迁移到examples。2、Field的附加参数在 Pydantic 模型中使用Field()时你也可以声明额外的examplesfromfastapiimportFastAPIfrompydanticimportBaseModel,Field appFastAPI()classItem(BaseModel):name:strField(examples[Foo])description:str|NoneField(defaultNone,examples[A very nice Item])price:floatField(examples[35.4])tax:float|NoneField(defaultNone,examples[3.2])app.put(/items/{item_id})asyncdefupdate_item(item_id:int,item:Item):results{item_id:item_id,item:item}returnresults3、JSON Schema 中的examples- OpenAPI在以下任意场景中使用Path()Query()Header()Cookie()Body()Form()File()你也可以声明一组examples这些带有附加信息的示例将被添加到它们在OpenAPI中的JSON Schema里。带有examples的Body这里我们向Body()传入examples其中包含一个期望的数据示例fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModel appFastAPI()classItem(BaseModel):name:strdescription:str|NoneNoneprice:floattax:float|NoneNoneapp.put(/items/{item_id})asyncdefupdate_item(item_id:int,item:Annotated[Item,Body(examples[{name:Foo,description:A very nice Item,price:35.4,tax:3.2,}],),],):results{item_id:item_id,item:item}returnresults其他版本non-annotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModel appFastAPI()classItem(BaseModel):name:strdescription:str|NoneNoneprice:floattax:float|NoneNoneapp.put(/items/{item_id})asyncdefupdate_item(item_id:int,item:ItemBody(examples[{name:Foo,description:A very nice Item,price:35.4,tax:3.2,}],),):results{item_id:item_id,item:item}returnresults带有多个examples的Body当然你也可以传入多个examplesfromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModel appFastAPI()classItem(BaseModel):name:strdescription:str|NoneNoneprice:floattax:float|NoneNoneapp.put(/items/{item_id})asyncdefupdate_item(*,item_id:int,item:Annotated[Item,Body(examples[{name:Foo,description:A very nice Item,price:35.4,tax:3.2,},{name:Bar,price:35.4,},{name:Baz,price:thirty five point four,},],),],):results{item_id:item_id,item:item}returnresults其他版本non-annotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModel appFastAPI()classItem(BaseModel):name:strdescription:str|NoneNoneprice:floattax:float|NoneNoneapp.put(/items/{item_id})asyncdefupdate_item(*,item_id:int,item:ItemBody(examples[{name:Foo,description:A very nice Item,price:35.4,tax:3.2,},{name:Bar,price:35.4,},{name:Baz,price:thirty five point four,},],),):results{item_id:item_id,item:item}returnresults这样做时这些示例会成为该请求体数据内部JSON Schema的一部分。不过在撰写本文时用于展示文档 UI 的 Swagger UI 并不支持显示JSON Schema中数据的多个示例,但有一种变通方法。OpenAPI 特定的examples在JSON Schema支持examples之前OpenAPI 就已支持一个同名但不同的字段examples。这个OpenAPI 特定的examples位于 OpenAPI 规范的另一处。它放在每个*路径操作*的详细信息中而不是每个 JSON Schema 里。而 Swagger UI 早就支持这个特定的examples字段。因此你可以用它在文档 UI 中展示不同的示例。这个 OpenAPI 特定字段examples的结构是一个包含多个示例的dict而不是一个list每个示例都包含会被添加到OpenAPI的额外信息。这不放在 OpenAPI 内部包含的各个 JSON Schema 里而是直接放在路径操作上。使用openapi_examples参数你可以在 FastAPI 中通过参数openapi_examples来声明这个 OpenAPI 特定的examples适用于Path()Query()Header()Cookie()Body()Form()File()这个dict的键用于标识每个示例每个值是另一个dict。examples中每个具体示例的dict可以包含summary该示例的简短描述。description较长描述可以包含 Markdown 文本。value实际展示的示例例如一个dict。externalValuevalue的替代项指向该示例的 URL。不过它的工具支持度可能不如value。你可以这样使用fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModel appFastAPI()classItem(BaseModel):name:strdescription:str|NoneNoneprice:floattax:float|NoneNoneapp.put(/items/{item_id})asyncdefupdate_item(*,item_id:int,item:Annotated[Item,Body(openapi_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}returnresults其他版本fromfastapiimportBody,FastAPIfrompydanticimportBaseModel appFastAPI()classItem(BaseModel):name:strdescription:str|NoneNoneprice:floattax:float|NoneNoneapp.put(/items/{item_id})asyncdefupdate_item(*,item_id:int,item:ItemBody(openapi_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}returnresults4、技术细节注此部分针对于FastAPI版本 **0.99.0以下版本 **。它们对更早版本OpenAPI 3.1.0 尚不可用之前更相关。在 OpenAPI 3.1.0 之前OpenAPI 使用的是一个更旧且经过修改的JSON Schema版本。当时 JSON Schema 没有examples所以 OpenAPI 在它修改过的版本中添加了自己的example字段。OpenAPI 还在规范的其他部分添加了example和examples字段Parameter Object规范中被 FastAPI 的以下内容使用Path()Query()Header()Cookie()Request Body Object中的content字段里的Media Type Object规范中被 FastAPI 的以下内容使用Body()File()Form()注意这个旧的、OpenAPI 特定的examples参数自 FastAPI0.103.0起改名为openapi_examples。JSON Schema 的examples字段后来JSON Schema 在新版本的规范中添加了examples字段。随后新的 OpenAPI 3.1.0 基于最新版本JSON Schema 2020-12其中包含了这个新的examples字段。现在这个新的examples字段优先于旧的单个且自定义的example字段后者已被弃用。在 JSON Schema 中这个新的examples字段只是一个由示例组成的list而不是像上面提到的 OpenAPI 其他位置那样带有额外元数据的dict。注意即使在 OpenAPI 3.1.0 发布、并与 JSON Schema 有了这种更简单的集成之后有一段时间里提供自动文档的 Swagger UI 并不支持 OpenAPI 3.1.0它自 5.0.0 版本起已支持 。因此FastAPI 0.99.0 之前的版本仍然使用低于 3.1.0 的 OpenAPI 版本。Pydantic 与 FastAPI 的examples当你在 Pydantic 模型中添加examples通过schema_extra或Field(examples[something])这些示例会被添加到该 Pydantic 模型的JSON Schema中。这个 Pydantic 模型的JSON Schema会被包含到你的 API 的OpenAPI中然后在文档 UI 中使用。在 FastAPI 0.99.0 之前的版本0.99.0 及以上使用更新的 OpenAPI 3.1.0当你在其他工具Query()、Body()等中使用example或examples时这些示例不会被添加到描述该数据的 JSON Schema 中甚至不会添加到 OpenAPI 自己的 JSON Schema 版本中而是会直接添加到 OpenAPI 的路径操作声明中在 OpenAPI 使用 JSON Schema 的部分之外。但现在 FastAPI 0.99.0 及以上使用 OpenAPI 3.1.0其使用 JSON Schema 2020-12以及 Swagger UI 5.0.0 及以上后一切更加一致示例会包含在 JSON Schema 中。Swagger UI 与 OpenAPI 特定的examples由于截至 2023-08-26Swagger UI 不支持多个 JSON Schema 示例用户无法在文档中展示多个示例。为了解决这个问题FastAPI0.103.0增加了支持可以通过新参数openapi_examples声明同样的旧式OpenAPI 特定的examples字段。十二、额外数据类型我们一直在使用常见的数据类型如:intfloatstrbool但是也可以使用更复杂的数据类型仍然会拥有现在已经看到的相同的特性:很棒的编辑器支持。传入请求的数据转换。响应数据转换。数据验证。自动注解和文档。1、其他数据类型下面是一些你可以使用的其他数据类型:UUID一种标准的 “通用唯一标识符” 在许多数据库和系统中用作ID。在请求和响应中将以str表示。datetime.datetime一个 Pythondatetime.datetime.在请求和响应中将表示为 ISO 8601 格式的str比如:2008-09-15T15:53:0005:00.datetime.datePythondatetime.date.在请求和响应中将表示为 ISO 8601 格式的str比如:2008-09-15.datetime.time一个 Pythondatetime.time.在请求和响应中将表示为 ISO 8601 格式的str比如:14:23:55.003.datetime.timedelta一个 Pythondatetime.timedelta.在请求和响应中将表示为float代表总秒数。Pydantic 也允许将其表示为 “ISO 8601 时间差异编码”, 查看文档了解更多信息。frozenset在请求和响应中作为 set对待在请求中列表将被读取消除重复并将其转换为一个set。在响应中set将被转换为list。产生的模式将指定那些set的值是唯一的 (使用 JSON Schema 的uniqueItems)。bytes标准的 Pythonbytes。在请求和响应中被当作str处理。生成的模式将指定这个str是binary“格式”。Decimal标准的 PythonDecimal。在请求和响应中被当做float一样处理。2、例下面是一个路径操作的示例其中的参数使用了上面的一些类型。注意函数内的参数有原生的数据类型例如你可以执行正常的日期操作fromdatetimeimportdatetime,time,timedeltafromtypingimportAnnotatedfromuuidimportUUIDfromfastapiimportBody,FastAPI appFastAPI()app.put(/items/{item_id})asyncdefread_items(item_id:UUID,start_datetime:Annotated[datetime,Body()],end_datetime:Annotated[datetime,Body()],process_after:Annotated[timedelta,Body()],repeat_at:Annotated[time|None,Body()]None,):start_processstart_datetimeprocess_after durationend_datetime-start_processreturn{item_id:item_id,start_datetime:start_datetime,end_datetime:end_datetime,process_after:process_after,repeat_at:repeat_at,start_process:start_process,duration:duration,}其他版本non_annotatedfromdatetimeimportdatetime,time,timedeltafromuuidimportUUIDfromfastapiimportBody,FastAPI appFastAPI()app.put(/items/{item_id})asyncdefread_items(item_id:UUID,start_datetime:datetimeBody(),end_datetime:datetimeBody(),process_after:timedeltaBody(),repeat_at:time|NoneBody(defaultNone),):start_processstart_datetimeprocess_after durationend_datetime-start_processreturn{item_id:item_id,start_datetime:start_datetime,end_datetime:end_datetime,process_after:process_after,repeat_at:repeat_at,start_process:start_process,duration:duration,}