Metadata y URLs de Docs¶

Puedes personalizar varias configuraciones de metadata en tu aplicación FastAPI.

Metadata para la API¶

Puedes establecer los siguientes campos que se usan en la especificación OpenAPI y en las interfaces automáticas de docs de la API:

Parameter Tipo Descripción

title str El título de la API.

summary str Un breve resumen de la API. Disponible desde OpenAPI 3.1.0, FastAPI 0.99.0.

description str Una breve descripción de la API. Puede usar Markdown.

version str La versión de la API. Esta es la versión de tu propia aplicación, no de OpenAPI. Por ejemplo 2.5.0.

terms_of_service str Una URL a los Términos de Servicio de la API. Si se proporciona, tiene que ser una URL.

contact

dict

The contact information for the exposed API. It can contain several fields.

Campos de contact

Parameter	Tipo	Descripción
`name`	`str`	El nombre identificador de la persona/organización de contacto.
`url`	`str`	La URL que apunta a la información de contacto. DEBE estar en formato de URL.
`email`	`str`	El correo electrónico de la persona/organización de contacto. DEBE estar en formato de correo electrónico.

license_info

dict

The license information for the exposed API. It can contain several fields.

Campos de license_info

Parameter	Tipo	Descripción
`name`	`str`	REQUIRED (si se establece `license_info`). El nombre de la licencia usada para la API.
`identifier`	`str`	Una expresión de licencia SPDX para la API. El campo `identifier` es mutuamente excluyente del campo `url`. Disponible desde OpenAPI 3.1.0, FastAPI 0.99.0.
`url`	`str`	Una URL a la licencia usada para la API. DEBE estar en formato de URL.

Puedes establecerlos de la siguiente manera:

Python 3.10+


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"}]

Consejo

Puedes escribir Markdown en el campo description y se renderizará en la salida.

Con esta configuración, las docs automáticas de la API se verían así:

Identificador de licencia¶

Desde OpenAPI 3.1.0 y FastAPI 0.99.0, también puedes establecer el license_info con un identifier en lugar de una url.

Por ejemplo:

Python 3.10+


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"}]

Metadata para tags¶

También puedes añadir metadata adicional para los diferentes tags usados para agrupar tus operaciones de path con el parámetro openapi_tags.

Toma una lista que contiene un diccionario por cada tag.

Cada diccionario puede contener:

name (required): un str con el mismo nombre de tag que usas en el parámetro tags en tus operaciones de path y APIRouters.
description: un str con una breve descripción para el tag. Puede tener Markdown y se mostrará en la interfaz de docs.
externalDocs: a dict describing external documentation with:
- description: un str con una breve descripción para la documentación externa.
- url (required): un str con la URL para la documentación externa.

Crear metadata para tags¶

Probémoslo en un ejemplo con tags para users y items.

Crea metadata para tus tags y pásala al parámetro openapi_tags:

Python 3.10+


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"}]

Ten en cuenta que puedes usar Markdown dentro de las descripciones, por ejemplo "login" se mostrará en negrita (login) y "fancy" se mostrará en cursiva (fancy).

Consejo

No tienes que añadir metadata para todos los tags que usas.

Usar tus tags¶

Usa el parámetro tags con tus operaciones de path (y APIRouters) para asignarlas a diferentes tags:

Python 3.10+


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"}]

Nota

Lee más sobre tags en Configuración de Operaciones de Path.

Revisar la documentación¶

Ahora, si revisas las docs, mostrarán toda la metadata adicional:

Orden de tags¶

El orden de cada diccionario de metadata de tags también define el orden mostrado en la interfaz de docs.

Por ejemplo, aunque users iría después de items en orden alfabético, se muestra antes de ellos, porque añadimos su metadata como el primer diccionario en la lista.

URL de OpenAPI¶

Por defecto, el esquema OpenAPI se sirve en /openapi.json.

Pero puedes configurarlo con el parámetro openapi_url.

Por ejemplo, para configurarlo para que se sirva en /api/v1/openapi.json:

Python 3.10+


from fastapi import FastAPI

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


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

Si quieres deshabilitar completamente el esquema OpenAPI puedes establecer openapi_url=None, eso también deshabilitará las interfaces de documentación que lo usan.

URLs de Docs¶

Puedes configurar las dos interfaces de documentación incluidas:

Swagger UI: served at /docs.
- Puedes establecer su URL con el parámetro docs_url.
- Puedes deshabilitarlo estableciendo docs_url=None.
ReDoc: served at /redoc.
- Puedes establecer su URL con el parámetro redoc_url.
- Puedes deshabilitarlo estableciendo redoc_url=None.

Por ejemplo, para configurar Swagger UI para que se sirva en /documentation y deshabilitar ReDoc:

Python 3.10+


from fastapi import FastAPI

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


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