Metadados e Urls de Documentos

Você pode personalizar várias configurações de metadados na sua aplicação FastAPI.

Metadados para API

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:

Python 3.8+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You 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/")
async def read_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:

Identificador de Licença

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:

Python 3.8+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You 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/")
async def read_items():
    return [{"name": "Katana"}]

Metadados para tags

Você também pode adicionar metadados adicionais para as diferentes tags usadas para agrupar suas operações de rota com o parâmetro openapi_tags.

Ele recebe uma lista contendo um dicionário para cada tag.

Cada dicionário pode conter:

• name (obrigatório): uma str com o mesmo nome da tag que você usa no parâmetro tags nas suas operações de rota e APIRouters.
• description: uma str com uma breve descrição da tag. Pode conter Markdown e será exibido na interface de documentação.
• externalDocs: um dict descrevendo a documentação externa com:
  • description: uma str com uma breve descrição da documentação externa.
  • url (obrigatório): uma str com a URL da documentação externa.

Criar Metadados para tags

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:

Python 3.8+

from fastapi import FastAPI

tags_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"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_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 suas tags

Use o parâmetro tags com suas operações de rota (e APIRouters) para atribuí-los a diferentes tags:

Python 3.8+

from fastapi import FastAPI

tags_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"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Informação

Leia mais sobre tags em Configuração de Operação de Caminho.

Cheque os documentos

Agora, se você verificar a documentação, ela exibirá todos os metadados adicionais:

Ordem das tags

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.

URL da OpenAPI

Por padrão, o esquema OpenAPI é servido em /openapi.json.

Mas você pode configurá-lo com o parâmetro openapi_url.

Por exemplo, para defini-lo para ser servido em /api/v1/openapi.json:

Python 3.8+

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]

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.

URLs da Documentação

Você pode configurar as duas interfaces de documentação incluídas:

• Swagger UI: acessível em /docs.
  • Você pode definir sua URL com o parâmetro docs_url.
  • Você pode desativá-la definindo docs_url=None.
• ReDoc: acessível em /redoc.
  • Você pode definir sua URL com o parâmetro redoc_url.
  • Você pode desativá-la definindo redoc_url=None.

Por exemplo, para definir o Swagger UI para ser servido em /documentation e desativar o ReDoc:

Python 3.8+

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]