Organización y mejora de documentación OpenAPI

Clase 14 de 19Curso 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.