URL-адреса метаданных и документации¶

Вы можете настроить несколько конфигураций метаданных в вашемFastAPI приложении.

Метаданные для API¶

Вы можете задать следующие поля, которые используются в спецификации OpenAPI и в UI автоматической документации API:

Вы можете задать их следующим образом:

fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou will be able to:* **Create users** (_not implemented_).* **Read users** (_not implemented_)."""app=FastAPI(title="ChimichangApp",description=description,summary="Deadpool's favorite app. Nuff said.",version="0.0.1",terms_of_service="http://example.com/terms/",contact={"name":"Deadpoolio the Amazing","url":"http://x-force.example.com/contact/","email":"dp@x-force.example.com",},license_info={"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]

С этой конфигурацией автоматическая документация API будет выглядеть так:

Идентификатор лицензии¶

Начиная с OpenAPI 3.1.0 и FastAPI 0.99.0, вы также можете задатьlicense_info с помощьюidentifier вместоurl.

К примеру:

fromfastapiimportFastAPIdescription="""ChimichangApp API helps you do awesome stuff. 🚀## ItemsYou can **read items**.## UsersYou will be able to:* **Create users** (_not implemented_).* **Read users** (_not implemented_)."""app=FastAPI(title="ChimichangApp",description=description,summary="Deadpool's favorite app. Nuff said.",version="0.0.1",terms_of_service="http://example.com/terms/",contact={"name":"Deadpoolio the Amazing","url":"http://x-force.example.com/contact/","email":"dp@x-force.example.com",},license_info={"name":"Apache 2.0","identifier":"Apache-2.0",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]

Метаданные для тегов¶

Вы также можете добавить дополнительные метаданные для различных тегов, используемых для группировки ваших операций пути с помощью параметраopenapi_tags.

Он принимает список, содержащий один словарь для каждого тега.

Каждый словарь может содержать в себе:

• name (обязательно):str-значение с тем же именем тега, которое вы используете в параметреtags в вашихоперациях пути иAPIRouterах.
• description:str-значение с кратким описанием для тега. Может содержать Markdown и будет отображаться в UI документации.
• externalDocs:dict-значение описывающее внешнюю документацию. Включает в себя:
  • description:str-значение с кратким описанием для внешней документации.
  • url (обязательно):str-значение с URL-адресом для внешней документации.

Создание метаданных для тегов¶

Давайте попробуем сделать это на примере с тегами дляusers иitems.

Создайте метаданные для ваших тегов и передайте их в параметреopenapi_tags:

fromfastapiimportFastAPItags_metadata=[{"name":"users","description":"Operations with users. The **login** logic is also here.",},{"name":"items","description":"Manage items. So _fancy_ they have their own docs.","externalDocs":{"description":"Items external docs","url":"https://fastapi.tiangolo.com/",},},]app=FastAPI(openapi_tags=tags_metadata)@app.get("/users/",tags=["users"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]

Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (login) и "fancy" будет отображаться курсивом (fancy).

Используйте собственные теги¶

Используйте параметрtags с вашимиоперациями пути (иAPIRouterами), чтобы присвоить им различные теги:

fromfastapiimportFastAPItags_metadata=[{"name":"users","description":"Operations with users. The **login** logic is also here.",},{"name":"items","description":"Manage items. So _fancy_ they have their own docs.","externalDocs":{"description":"Items external docs","url":"https://fastapi.tiangolo.com/",},},]app=FastAPI(openapi_tags=tags_metadata)@app.get("/users/",tags=["users"])asyncdefget_users():return[{"name":"Harry"},{"name":"Ron"}]@app.get("/items/",tags=["items"])asyncdefget_items():return[{"name":"wand"},{"name":"flying broom"}]

Проверьте документацию¶

Теперь, если вы проверите документацию, вы увидите всю дополнительную информацию:

Порядок расположения тегов¶

Порядок расположения словарей метаданных для каждого тега определяет также порядок, отображаемый в UI документации.

К примеру, несмотря на то, чтоusers будут идти послеitems в алфавитном порядке, они отображаются раньше, потому что мы добавляем свои метаданные в качестве первого словаря в списке.

URL-адрес OpenAPI¶

По умолчанию схема OpenAPI отображена по адресу/openapi.json.

Но вы можете изменить это с помощью параметраopenapi_url.

К примеру, чтобы задать её отображение по адресу/api/v1/openapi.json:

fromfastapiimportFastAPIapp=FastAPI(openapi_url="/api/v1/openapi.json")@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]

Если вы хотите отключить схему OpenAPI полностью, вы можете задатьopenapi_url=None, это также отключит пользовательские интерфейсы документации, которые её используют.

URL-адреса документации¶

Вы можете изменить конфигурацию двух пользовательских интерфейсов документации, которые включены:

• Swagger UI: отображаемый по адресу/docs.
  • Вы можете задать его URL с помощью параметраdocs_url.
  • Вы можете отключить это с помощью настройкиdocs_url=None.
• ReDoc: отображаемый по адресу/redoc.
  • Вы можете задать его URL с помощью параметраredoc_url.
  • Вы можете отключить это с помощью настройкиredoc_url=None.

К примеру, чтобы задать отображение Swagger UI по адресу/documentation и отключить ReDoc:

fromfastapiimportFastAPIapp=FastAPI(docs_url="/documentation",redoc_url=None)@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]