Documentación automática con Swagger

¿Qué es la documentación autogenerada en FAS API?

La documentación autogenerada en FAS API es una herramienta interactiva que se genera automáticamente usando Swagger. Esta documentación sigue los estándares abiertos de OpenAPI y proporciona una descripción detallada de los endpoints disponibles en tu aplicación. Lo más notable es que puedes acceder a esta documentación simplemente añadiendo /docs a tu URL base, y así visualizar toda la información relevante.

¿Qué contiene la documentación generada?

La documentación muestra varios elementos clave, incluyendo:

• Título y versión: Proporciona información básica sobre la aplicación y su versión actual.

• Enlace a openapi.json: Un archivo que contiene un objeto JSON con toda la información de los endpoints.

• Rutas disponibles: Muestra cada una de las rutas de la aplicación, sus respuestas, y puede incluir parámetros de URL cuando se agreguen.

¿Cómo se puede probar la API directamente desde la documentación?

Una de las características más útiles es que puedes probar los endpoints directamente desde la documentación. Al seleccionar "Try it out", puedes ejecutar peticiones y verificar las respuestas directamente en el navegador, lo que facilita la verificación de funcionalidades sin necesitad de herramientas externas.

¿Cómo modificar la información en la documentación?

Modificar la documentación es sencillo y se realiza directamente desde el código de tu aplicación. Aquí te mostramos cómo ajustar algunos elementos:

Cambiar el título de la documentación

En tu editor de código, después de crear tu aplicación, puedes definir el título utilizando:

app.title = "Mi aplicación con FastAPI"

Guarda los cambios, recarga la página de la documentación, y verás que el nuevo título aparecerá de inmediato.

Actualizar la versión de la aplicación

Del mismo modo, puedes ajustarla versión:

app.version = "0.0.1"

Asegúrate de guardarlo dentro de comillas. Tras actualizar y recargar, la nueva versión será visible en la documentación.

Agrupar rutas con etiquetas

Las etiquetas ayudan a organizar los endpoints de manera más eficiente. Para añadir etiquetas:

@app.get("/", tags=["home"])

Esto ubica la ruta en un grupo llamado "home" que se refleja inmediatamente al recargar la documentación. Más adelante, puedes asignar etiquetas como "movies" para endpoints relacionados con películas, favoreciendo una estructura clara y ordenada.

Recomendaciones y mejores prácticas

La autogeneración de documentación es una herramienta poderosa en FAS API que mejora considerablemente el flujo de desarrollo y la experiencia del usuario al interactuar con la API. Aquí algunos consejos:

• Revisar y actualizar: Siempre verifica que los cambios en tu código se reflejan adecuadamente en la documentación.

• Utiliza tags: Organiza las rutas con etiquetas para facilitar la navegación por la documentación.

• Itera y mejora: A medida que tu API crezca, ajusta la documentación para que refleje los cambios y nuevas funcionalidades.

Continúa explorando y experimentando con FAS API para dominar el manejo de documentación y desarrollar aplicaciones robustas y bien documentadas.