Неочевидных моментов в уроке не обнаружено, но я рад сообщить, что дополнил базу инструмента для импорта модулей и классов в python классами, использующимися в уроке.
Вы можете объявлять примеры данных, которые ваше приложение может получать.
Вот несколько способов сделать это.
Дополнительные данные JSON Schema в моделях Pydantic¶
Вы можете объявить examples для модели Pydantic, которые будут добавлены в сгенерированную JSON Schema.
fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonemodel_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.
Вы можете установить "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. 🤓
При использовании Field() с моделями Pydantic вы также можете объявить дополнительные examples:
fromfastapiimportFastAPIfrompydanticimportBaseModel,Fieldapp=FastAPI()classItem(BaseModel):name:str=Field(examples=["Foo"])description:str|None=Field(default=None,examples=["A very nice Item"])price:float=Field(examples=[35.4])tax:float|None=Field(default=None,examples=[3.2])@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults
Здесь мы передаём examples, содержащие один пример данных, ожидаемых в Body():
fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.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
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item=Body(examples=[{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,}],),):results={"item_id":item_id,"item":item}returnresults
Вы, конечно, также можете передать несколько examples:
fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.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
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.put("/items/{item_id}")asyncdefupdate_item(*,item_id:int,item: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
Когда вы это сделаете, примеры станут частью внутренней JSON Schema для этих данных тела.
Тем не менее, на момент написания этого текста, Swagger UI, инструмент, отвечающий за показ интерфейса документации, не поддерживает отображение нескольких примеров для данных в JSON Schema. Но читайте ниже об обходном пути.
Ещё до того, как JSON Schema поддержала examples, OpenAPI уже поддерживал другое поле, также называемое examples.
Эти специфичные для OpenAPIexamples находятся в другом разделе спецификации OpenAPI. Они находятся в деталях для каждой операции пути, а не внутри каждой JSON Schema.
И Swagger UI уже довольно давно поддерживает это особое поле examples. Так что вы можете использовать его, чтобы показывать разные примеры в интерфейсе документации.
Форма этого специфичного для OpenAPI поля examples — это dict с несколькими примерами (вместо list), каждый с дополнительной информацией, которая также будет добавлена в OpenAPI.
Это не помещается внутрь каждой JSON Schema, содержащейся в OpenAPI, это помещается снаружи, непосредственно в операцию пути.
Вы можете объявить специфичные для OpenAPI examples в FastAPI с помощью параметра openapi_examples для:
Path()
Query()
Header()
Cookie()
Body()
Form()
File()
Ключи dict идентифицируют каждый пример, а каждое значение — это другой dict.
Каждый конкретный dict примера в examples может содержать:
summary: Краткое описание для примера.
description: Длинное описание, которое может содержать текст Markdown.
value: Это фактический показанный пример, например dict.
externalValue: альтернатива value, URL, указывающий на пример. Хотя это может поддерживаться не таким большим количеством инструментов, как value.
Вы можете использовать это так:
fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.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
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.put("/items/{item_id}")asyncdefupdate_item(*,item_id:int,item: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
Но затем JSON Schema добавила поле examples в новую версию спецификации.
И затем новый OpenAPI 3.1.0 был основан на последней версии (JSON Schema 2020-12), которая включала это новое поле examples.
И теперь это новое поле examples имеет приоритет над старым одиночным (и пользовательским) полем example, которое теперь устарело.
Это новое поле examples в JSON Schema — это просто list примеров, а не dict с дополнительными метаданными, как в других местах OpenAPI (описано выше).
Примечание
Даже после того, как OpenAPI 3.1.0 был выпущен с этой новой более простой
интеграцией с JSON Schema, в течение некоторого времени Swagger UI, инструмент, который
обеспечивает автоматическую документацию, не поддерживал OpenAPI 3.1.0 (он поддерживает
начиная с версии 5.0.0 🎉).
Из-за этого версии FastAPI до 0.99.0 всё ещё использовали версии OpenAPI ниже 3.1.0.
Когда вы добавляете examples внутрь модели Pydantic, используя schema_extra или Field(examples=["something"]), этот пример добавляется в JSON Schema для этой модели Pydantic.
И эта JSON Schema модели Pydantic включается в OpenAPI вашего API, а затем используется в интерфейсе документации.
В версиях FastAPI до 0.99.0 (0.99.0 и выше используют более новый OpenAPI 3.1.0), когда вы использовали example или examples с любыми другими утилитами (Query(), Body()
и т.д.), эти примеры не добавлялись в JSON Schema, описывающую
эти данные (даже не в собственную версию JSON Schema от OpenAPI), они
добавлялись непосредственно в объявление операции пути в 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 не поддерживал несколько примеров JSON Schema (по
состоянию на 2023-08-26), у пользователей не было способа показать несколько примеров в
документации.
Чтобы решить эту проблему, FastAPI 0.103.0добавил поддержку объявления того же старого специфичного для OpenAPI поля examples с новым параметром openapi_examples. 🤓
Раньше я говорил, что не очень люблю историю... а теперь вот даю «уроки технической истории». 😅
Короче говоря, обновитесь до FastAPI 0.99.0 или выше, и всё станет гораздо проще, согласованнее и интуитивнее, и вам не нужно знать все эти исторические детали. 😎