Documentación interactiva de API de FastAPI

FastAPI genera automáticamente documentación interactiva de API basada en las anotaciones de tipo en el código, y proporciona por defecto dos interfaces: Swagger UI y ReDoc. Los desarrolladores pueden probar la API directamente en la documentación sin necesidad de herramientas adicionales.

Acceder a la documentación de la API

Después de ejecutar la aplicación FastAPI, visita las siguientes direcciones para ver la documentación:

DirecciónTipo de documentaciónCaracterísticas
http://127.0.0.1:8000/docsSwagger UIPruebas interactivas, haz clic en "Try it out" para enviar la solicitud
http://127.0.0.1:8000/redocReDocBuena experiencia de lectura, adecuada para navegar y consultar definiciones de API
http://127.0.0.1:8000/openapi.jsonOpenAPI JSONEspecificación OpenAPI original en JSON, disponible para consumo por herramientas

Swagger UI

Swagger UI proporciona una interfaz de usuario intuitiva que permite probar la API directamente en el navegador:

Pasos para probar la API

  1. Haz clic en la ruta a probar para expandir los detalles
  2. Haz clic en el botón"Try it out"Botón
  3. Rellena los valores de los parámetros
  4. Haz clic en el botón"Execute"Botón para enviar la solicitud
  5. Ver el resultado de la respuesta

ReDoc

ReDoc se centra en la legibilidad de la documentación, adecuado para navegar por las definiciones de la API:

Especificación OpenAPI

FastAPI utiliza el estándarOpenAPIpara convertir la API en un "esquema" (Schema). Visitahttp://127.0.0.1:8000/openapi.jsonpara ver el JSON original de OpenAPI:

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/{item_id}": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response"
                    }
                }
            }
        }
    }
}

Usos de la especificación OpenAPI:

  • Impulsa los sistemas de documentación Swagger UI y ReDoc
  • Genera automáticamente código de cliente en varios lenguajes
  • Integración con herramientas de prueba de API (como Postman)
  • Compatible con una gran cantidad de herramientas y plataformas de terceros

Personalizar la información de la documentación de la API

Al crear una instancia de FastAPI, puedes personalizar los metadatos de la documentación:

Ejemplo

from fastapi import FastAPI

app = FastAPI(
    title="Mi API",                    # Título de la API
    description="Esta es una API de ejemplo que muestra la funcionalidad de personalización de la documentación",  # Descripción de la API
    version="1.0.0",                    # Versión de la API
    terms_of_service="http://example.com/terms/",  # URL de los términos de servicio
    contact={                           # Información de contacto
        "name": "Desarrollador",
        "url": "http://example.com/contact/",
        "email": "[email protected]",
    },
    license_info={                      # Información de la licencia
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

Añadir información de documentación a las rutas

Se puede añadir información de documentación detallada a cada ruta en el decorador y en la función:

Ejemplo

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get(
    "/items/{item_id}",
    summary="Obtener información del producto",              # Resumen breve
    description="Obtener la información detallada del producto según su ID",  # Descripción detallada
    response_description="Objeto de información del producto",   # Descripción de la respuesta
    tags=["Gestión de productos"],                   # Etiqueta de agrupación
)
async def read_item(
    item_id: Annotated[int, Path(ge=1, description="ID del producto")],
    q: Annotated[str | None, Query(description="Palabra clave de búsqueda")] = None,
):
    """
Obtener información del producto:

- **item_id**: Identificador único del producto
- **q**: Palabra clave de búsqueda opcional
    """
    return {"item_id": item_id, "q": q}

Descripción de los parámetros de documentación:

ParámetroUbicaciónDescripción
summaryDecoradorResumen breve de la ruta, que se muestra en la lista de rutas
descriptionDecoradorDescripción detallada de la ruta, compatible con Markdown
response_descriptionDecoradorDescripción de la respuesta
tagsDecoradorAgrupación de rutas, que se muestra clasificada por etiquetas en la documentación
docstringCuerpo de la funciónEl docstring de la función, que se muestra como descripción

Si se establecen tantodescriptioncomo el docstring de la función,descriptiontiene prioridad. El docstring es compatible con formato Markdown y es adecuado para escribir descripciones más largas.

Agrupar con tags

tagsEl parámetro puede agrupar rutas relacionadas para mostrarlas de forma más clara en la documentación:

Ejemplo

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/", tags=["Gestión de usuarios"])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


@app.get("/items/", tags=["Gestión de productos"])
async def read_items():
    return [{"name": "Foo"}, {"name": "Bar"}]

En Swagger UI, las rutas se muestran agrupadas por etiquetas.

Deshabilitar la documentación

En un entorno de producción, puede que quieras deshabilitar la documentación automática:

Ejemplo

from fastapi import FastAPI

# Deshabilitar la documentación
app = FastAPI(docs_url=None, redoc_url=None)

Resumen

  • FastAPI genera automáticamente dos tipos de documentación interactiva: Swagger UI y ReDoc
  • El contenido de la documentación se genera automáticamente basado en las anotaciones de tipo en el código; cuando el código se actualiza, la documentación se sincroniza automáticamente
  • Usatitle、description、tagsy otros parámetros para personalizar la información de la documentación
  • El docstring de la función también aparece en la documentación
  • En producción se puede usardocs_url=Nonepara deshabilitar la documentación
Otras extensiones