Metadados e Urls de Documentos¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

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.9+

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.9+

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": "Apache-2.0",
    },
)


@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.9+

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.9+

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 rota.

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.9+

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.9+

from fastapi import FastAPI

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


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