Lista de verificación de documentación de OpenAPI

Contrato como única fuente de verdad

Mantengo la descripción de OpenAPI en el mismo repositorio que el código del servicio. Esto hace que el archivo sea visible para cualquier persona que lea el código fuente y permite que el control de versiones muestre cada cambio.

Ubicación del archivo

Coloco el archivo en docs/openapi.yaml en la raíz del repositorio. La ruta es corta, fácil de encontrar y no entra en conflicto con los assets generados.

Prácticas de control de versiones

Cada edición del contrato de API pasa por una solicitud de extracción. Requiero al menos un aprobador que verifique que la descripción coincide con los cambios de código. También ejecuto un paso de lint en la tubería de CI antes de que la solicitud de extracción pueda ser fusionada.

Evitando la deriva con pruebas de contrato

Agrego una suite de pruebas que llama al servicio en ejecución y valida cada respuesta contra el esquema de OpenAPI. Si el servicio devuelve algo que no coincide con el contrato, la prueba falla y el equipo recibe retroalimentación inmediata.

- El contrato vive junto al código, no en una wiki separada - Las revisiones de solicitudes de extracción detectan las discrepancias temprano - Las pruebas automatizadas protegen contra la deriva en tiempo de ejecución - El historial muestra quién cambió qué y por qué

Documentación de errores

Los integradores primero notan problemas cuando reciben un error que no esperaban. Describir las formas de 4xx y 5xx reduce los tickets de soporte y permite que los generadores de clientes produzcan código de manejo de errores correcto.

Definir formas de 4xx

Agrego una sección components.responses para cada error de cliente que la API puede devolver. Las entradas típicas incluyen 400 Solicitud incorrecta para problemas de validación, 401 No autorizado para credenciales perdidas o inválidas, 403 Prohibido para ámbitos insuficientes y 422 Entidad no procesable para violaciones de reglas de negocio.

Definir formas de 5xx

Los errores del servidor son menos frecuentes, pero aún necesitan documentación. Describo una respuesta genérica de error interno del servidor 500 y, cuando corresponda, una respuesta de servicio no disponible 503 con un encabezado Retry-After.

Ejemplo de respuesta de error

- Documentar cada código de error distinto que el servicio puede emitir - Proporcionar un mensaje corto y una matriz de detalles opcional - Mantener los esquemas de error reutilizables en todos los puntos finales - Actualizar la documentación de errores cuando se agregan nuevas reglas de validación

Ejemplos junto a esquemas

Cuando un desarrollador ve un ejemplo claro de solicitud o respuesta, el tiempo dedicado a adivinar disminuye dramáticamente. Coloco ejemplos directamente al lado del esquema que ilustran, utilizando los campos de ejemplo o ejemplos de OpenAPI.

Ejemplos en línea

Para objetos simples, agrego un valor de ejemplo dentro del esquema. Esto se muestra en Swagger UI y Redoc sin archivos adicionales.

Ejemplos externos

Para cargas más grandes, mantengo una carpeta de ejemplos separada y la referencia con $ref:./examples/payment-request.json. Esto mantiene el archivo principal legible mientras aún proporciona ricos ejemplos.

Generación de fragmentos de código

APIDocGen lee el archivo OpenAPI y crea fragmentos de código para curl, JavaScript fetch y Python requests para cada operación. Almaceno esos fragmentos de código en el directorio docs/snippets/ y los enlazo desde la descripción de la operación.

- Los ejemplos reducen el va y vién en Slack o correo electrónico - Los ejemplos en línea funcionan bien para pequeños DTO - Los archivos externos mantienen la especificación principal organizada - Los fragmentos de código generados dan a los desarrolladores un punto de partida para copiar y pegar

Lint en CI

Una referencia rota o una operaciónId faltante puede silenciosamente dañar los generadores de clientes y los sitios de documentación. Ejecuto un linter como parte de la tubería de compilación y hago que la compilación falle en cualquier error.

Elección de un linter

Utilizo Spectral con el conjunto de reglas spectral:oas porque entiende OpenAPI 3.1 y me permite agregar reglas personalizadas para nuestras convenciones internas.

Pasos de integración de CI

En el flujo de trabajo de GitHub Actions agrego un paso que instala Spectral a través de npm, luego ejecuta spectral lint docs/openapi.yaml. El paso utiliza la configuración continue-on-error: false para que cualquier problema detenga la tubería.

Control de $ref y operationId

El linter verifica que cada $ref> se pueda resolver y que cada operationId> sea único en todo el archivo. También hago cumplir que todos los caminos tengan un summary> y una description>.

Regla | Severidad | Qué verifica no-unresolved-ref | error | Todos los punteros $ref deben resolverse operation-operationId | error | Cada operación debe tener una operationId no-duplicate-operationId | error | Los valores operationId deben ser únicos camino-resumen | advertencia | Cada elemento de camino necesita un resumen camino-descripción | advertencia | Cada elemento de camino necesita una descripción

- El paso de lint se ejecuta en cada push y solicitud de extracción - Los errores bloquean las fusiones, las advertencias aparecen en la salida de comprobación - Las reglas personalizadas pueden hacer cumplir la nomenclatura específica de la empresa - La salida es fácil de leer en la interfaz de usuario de comprobaciones de GitHub

Qué no es esto

Quiero ser honesto sobre los límites de una lista de verificación. Seguir estos elementos mejora la calidad de su descripción de OpenAPI, pero no garantiza una documentación perfecta en todas las situaciones.

No es una garantía de documentación perfecta

Incluso con un archivo limpio y ricos ejemplos, los desarrolladores pueden encontrar aún lagunas si el comportamiento de la API cambia en tiempo de ejecución. La lista de verificación ayuda a detectar muchos problemas, pero aún necesitas verificar el servicio en vivo.

No reemplaza las pruebas en tiempo de ejecución

Las pruebas de contrato que validan respuestas contra el esquema son valiosas, pero no reemplazan las pruebas exploratorias, las pruebas de rendimiento o el análisis de seguridad. Trata la lista de verificación como una capa de defensa.

No es un sustituto de un buen diseño

Si la API subyacente es confusa o inconsistente, ninguna cantidad de documentación la hará fácil de usar. Dedica tiempo a la modelización de recursos limpios, la nomenclatura clara y los códigos de error sensatos antes de invertir mucho en documentación.

- La lista de verificación mejora la coherencia, no la corrección de la lógica de negocio - La supervisión en tiempo de ejecución es aún necesaria para detectar desviaciones después de la implementación - Un buen diseño reduce la cantidad de texto explicativo requerido - Trata la documentación como un artefacto vivo, no como una tarea de una sola vez

Mantener la documentación actualizada

Un archivo OpenAPI puede quedarse desactualizado si nadie se da cuenta de que el código ha divergido. Establezco hábitos ligeros que hacen que los archivos desactualizados sean visibles antes de que causen confusión.

Generación automática

Configuro la tubería de CI para regenerar la documentación HTML (usando Redoc) después de cada construcción exitosa y publico la salida en un host de sitio estático. La URL de la documentación publicada aparece en el comentario de la solicitud de extracción, por lo que los revisores pueden ver la versión renderizada al instante.

Proceso de revisión

Cada vez que un contribuyente modifica un controlador o un modelo de datos, le pido que abra el archivo OpenAPI y verifique que las rutas, parámetros y respuestas relevantes reflejen el cambio. Agrego un comentario recordatorio en la plantilla de solicitud de extracción.

Monitoreo de archivos desactualizados

Ejecuto un trabajo nocturno que git-diff el archivo OpenAPI contra la versión de la semana anterior. Si la diferencia muestra más de treinta líneas cambiadas, el trabajo publica un mensaje en el canal del equipo solicitando una revisión rápida.

- La documentación publicada da una pista visual de que la fuente es actual - Los recordatorios de revisión mantienen el contrato cerca del código - La diferencia automática resalta las ediciones grandes e involuntarias - Todos los pasos se ejecutan sin intervención manual

Lista de verificación del operador para la documentación de OpenAPI (2026)

Mantengo una lista de verificación escrita al lado de cada lanzamiento que toca este tema. La lista es aburrida a propósito: nombrar al propietario, nombrar el artefacto de evidencia y nombrar la reversión. Si un paso no puede producir un archivo, un ticket o una línea de registro, no es un paso, es un deseo.

Antes de cambiar la producción

- Congelar la rama o revisión de configuración que se medirá. - Registrar el modo de fallo actual con una entrada concreta y una salida concreta. - Confirmar qué identidad ejecuta el trabajo y si esa identidad puede acceder a datos que no debería. - Abrir las referencias principales que se citarán: https://learn.openapis.org/best-practices.html, https://redocly.com/docs/redoc.

Mientras se ejecuta la verificación

- Preferir un camino reproducible sobre diez capturas de pantalla anecdóticas. - Escribir el resultado seguro esperado antes de activar la herramienta o consulta. - Capturar el comando exacto, la invitación, el esquema o la expresión regular bajo prueba, no una paráfrasis. - Si el sistema puede actuar (enviar, escribir, eliminar, transferir), requerir un límite de confirmación en el mismo paso.

Después de terminar

- Archivar el riesgo residual con un propietario y una fecha, incluso cuando el análisis es limpio. - No convertir una verificación verde en lenguaje de ventas que reclame completitud. - Volver a ejecutar la misma lista de verificación cuando cambian el modelo, el esquema de la herramienta o las reglas de validación.

Señal | Qué registrar | Detener el envío? Escritura o envío inesperado | Nombre de la herramienta, argumentos, identidad | Sí hasta que esté bloqueado Falta de confirmación en acción destructiva | Ruta de llamada y omisión | Sí Texto no confiable tratado como instrucción | Superficie de origen y acción resultante | Sí para el alcance del agente Analizador limpio, juicio abierto | Elementos diferidos + propietario | Solo si el camino central es seguro

api-docgen ayuda con el primer paso medible. Las opciones de arquitectura, el visto bueno legal y las reclamaciones que enfrentan al cliente aún necesitan un propietario humano. Tratar cada fila de la lista de verificación como soporte de decisión, no como certificado.

Cómo explico los límites a los compradores

Cuando un prospecto pregunta si el producto "cubre todo", respondo con el límite: las comprobaciones automatizadas detectan patrones conocidos; las cadenas novedosas y el juicio de política aún necesitan revisión. Esa honestidad mantiene la carga de soporte baja y mantiene el blog alineado con lo que el producto realmente hace.

Si necesita una segunda opinión, combine este escrito con las referencias a continuación y con su propia reproducción de staging. No omita el paso de reproducción solo porque un modelo escribió un resumen confiado.

Referencias

- https://learn.openapis.org/best-practices.html - https://redocly.com/docs/redoc - https://spec.openapis.org/oas/latest.html - https://spec.openapis.org/oas/latest.html#schema-object