Você pode definir os seguintes campos que são usados na especificação OpenAPI e nas interfaces automáticas de documentação da API:
Parâmetro
Tipo
Descrição
title
str
O título da API.
summary
str
Um breve resumo da API. Disponível desde OpenAPI 3.1.0, FastAPI 0.99.0.
description
str
Uma breve descrição da API. Pode usar Markdown.
version
string
A versão da API. Esta é a versão da sua aplicação, não do OpenAPI. Por exemplo, 2.5.0.
terms_of_service
str
Uma URL para os Termos de Serviço da API. Se fornecido, deve ser uma URL.
contact
dict
As informações de contato da API exposta. Pode conter vários campos. Campos de contact
Parâmetro
Tipo
Descrição
name
str
O nome identificador da pessoa/organização de contato.
url
str
A URL que aponta para as informações de contato. DEVE estar no formato de uma URL.
email
str
O endereço de e-mail da pessoa/organização de contato. DEVE estar no formato de um endereço de e-mail.
license_info
dict
As informações de licença para a API exposta. Ela pode conter vários campos. Campos de license_info
Parâmetro
Tipo
Descrição
name
str
OBRIGATÓRIO (se um license_info for definido). O nome da licença usada para a API.
identifier
str
Uma expressão de licença SPDX para a API. O campo identifier é mutuamente exclusivo do campo url. Disponível desde OpenAPI 3.1.0, FastAPI 0.99.0.
url
str
Uma URL para a licença usada para a API. DEVE estar no formato de uma URL.
Você pode defini-los da seguinte maneira:
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"}]
Dica
Você pode escrever Markdown no campo description e ele será renderizado na saída.
Com essa configuração, a documentação automática da API se pareceria com:
Desde o OpenAPI 3.1.0 e FastAPI 0.99.0, você também pode definir o license_info com um identifier em vez de uma url.
Por exemplo:
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":"MIT",},)@app.get("/items/")asyncdefread_items():return[{"name":"Katana"}]
Vamos tentar isso em um exemplo com tags para users e items.
Crie metadados para suas tags e passe-os para o parâmetro 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"}]
Observe que você pode usar Markdown dentro das descrições. Por exemplo, "login" será exibido em negrito (login) e "fancy" será exibido em itálico (fancy).
Dica
Você não precisa adicionar metadados para todas as tags que você usa.
Use o parâmetro tags com suas operações de rota (e APIRouters) para atribuí-los a diferentes 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"}]
A ordem de cada dicionário de metadados de tag também define a ordem exibida na interface de documentação.
Por exemplo, embora users apareça após items em ordem alfabética, ele é exibido antes deles, porque adicionamos seus metadados como o primeiro dicionário na lista.
Se você quiser desativar completamente o esquema OpenAPI, pode definir openapi_url=None, o que também desativará as interfaces de documentação que o utilizam.