Organización y mejora de documentación OpenAPI
Clase 14 de 19 • Curso de API First
Resumen
Crear documentación clara y útil para una API es clave para facilitar su implementación y uso. Mejorar tu documento OpenAPI incluye pasos precisos que brindan estructura, detalles técnicos, información de contacto efectiva y recursos adicionales que incrementan la practicidad del documento. Veamos cómo lograr que tu documentación sea más funcional, organizada y accesible para desarrolladores.
¿Qué elementos esenciales debe incluir tu documento OpenAPI?
Para comenzar a mejorar tu documento, es vital incluir información precisa sobre la API. Algunos puntos clave que puedes integrar son:
- Nombre descriptivo: coloca un nombre que represente claramente la función o propósito de tu API, por ejemplo, "Fake API Store".
- Descripción detallada: define claramente las funciones, los alcances y alcances particulares mediante formato markdown, enlaces útiles o listas de recursos.
- Servidores: aquí no es necesario hacer cambios si previamente están configurados correctamente.
- Términos del servicio: ofrece detalles claros sobre las condiciones de uso.
- Información de contacto: permite contacto directo proporcionando nombres, correos electrónicos y URLs correspondientes.
- Licencia: especifica claramente bajo cuál licencia se puede utilizar la API, por ejemplo, licencia MIT.
- Documentación externa: agrega enlaces referidos a información adicional relacionada al contexto de uso o implementación.
- Número de versión: llevar un control estricto y claro de versiones (por ejemplo, versión 1.2.3, indicando versiones principales, secundarias y reparaciones).
¿Cuál es la mejor forma de organizar tu documentación OpenAPI?
Una manera eficiente de organizar la información es utilizando etiquetas (tags). Estas etiquetas separan claramente los diferentes tipos de recursos o funcionalidades que ofrece tu API, facilitando a los usuarios encontrar rápidamente lo que están buscando.
Pasos para utilizar etiquetas:
- Añadir una sección "tags" en la raíz del archivo de configuración para definir etiquetas como "users" o "products".
- Asignar estas etiquetas directamente a cada endpoint en el documento OpenAPI.
- Utilizar ayudas automáticas de editores modernos que completan la asignación mediante inteligencia artificial, ahorrando tiempo.
Por ejemplo, para asignar la etiqueta users, el endpoint luciría algo así:
post:
tags:
- Users
Una vez realizado este procedimiento, tus recursos estarán claramente agrupados, ofreciendo una documentación más organizada y amigable para los desarrolladores que consultan el documento.
¿Cuál es el procedimiento para revisar y actualizar tu documentación?
Cada vez que realices cambios significativos como los mencionados anteriormente, recuerda actualizar tu servidor para reflejar esos cambios.
Es recomendable:
- Guardar los cambios realizados en el documento OpenAPI desde tu editor de código.
- Detener y reiniciar el servidor ejecutando nuevamente comandos como npm run dev
.
- Refrescar la página de documentación generada para confirmar que los cambios realizados estén reflejados claramente.
De esta manera, tienes una documentación actualizada, bien organizada y fácil de consultar, optimizando así la experiencia del desarrollador que implementará o utilizará tu API.
Cuéntanos si esta guía práctica te resultó útil o qué otros aspectos relacionados con documentación de APIs te interesa aprender.