Organización y mejora de documentación OpenAPI

Contenido del curso

Introducción y Fundamentos de API First

Herramientas y Validación de APIs

Versionado, Prototipado y Documentación

Validación y Pruebas de Contratos

Seguridad

19
Proteger endpoints con JWT en OpenAPI
07:40 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:008:10

Organización y mejora de documentación OpenAPI

Curso de API First

Clase 14 de 19

Clase 14 / 19

Recursos

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.

Introducción y Fundamentos de API First

API First con OpenAPI antes de programar

Especificación OpenAPI para documentar APIs RESTful

Configuración inicial de proyecto ExpressJS con especificación OpenAPI

Construcción de API con Express y documentación Swagger

Herramientas y Validación de APIs

Validación automática con Express OpenAPI Validator

Validación automática con OpenAPI en Express

Múltiples respuestas HTTP en OpenAPI

Cómo la IA genera endpoints desde OpenAPI

Esquemas reutilizables de productos en OpenAPI

Endpoints de productos con esquemas reutilizables

API First con IA: construye CRUD sin codificar

Versionado, Prototipado y Documentación

Versionado de APIs con OpenAPI

Cómo crear un mock server con Prism CLI

Organización y mejora de documentación OpenAPI

Agregar ejemplos reales en especificaciones OpenAPI

Validación y Pruebas de Contratos

Errores en OpenAPI que Swagger Editor detecta

Importación de OpenAPI a Postman para automatizar pruebas

Pruebas de API con Newman en tu pipeline

Seguridad

Proteger endpoints con JWT en OpenAPI

Organización y mejora de documentación OpenAPI

Progreso del curso

Introducción y Fundamentos de API First

Herramientas y Validación de APIs

Versionado, Prototipado y Documentación

Validación y Pruebas de Contratos

Seguridad

Recursos

Recursos