La documentación generada todavía puede ser falsa, de dos maneras. Puede estar desactualizada, porque nadie la regeneró. Y el código puede cambiar el contrato sin que nadie note que lo hizo.
Las dos se resuelven tratando el documento OpenAPI como un artefacto de build que se sube al repositorio.
Sube el documento al repositorio. Expórtalo a un archivo del repositorio, openapi.json, y haz commit. Ahora un cambio en el contrato de la API aparece en un pull request como un diff de ese archivo, donde quien revisa puede verlo. «Añadiste un campo obligatorio» deja de ser algo que un consumidor descubre y pasa a ser algo que un revisor aprueba.
Haz fallar el build cuando esté desactualizado. En el pipeline del Capítulo 14, regenera el documento y compara:
- run: php artisan scramble:export --path=openapi.json
- run: git diff --exit-code openapi.json
La primera línea es el comando de exportación de Scramble en el momento de escribir esto. Scribe tiene el suyo.
Si el código y el documento subido no coinciden, el build está en rojo. El desarrollador regenera, mira el diff y hace commit.
Detecta los cambios incompatibles de forma mecánica. El Capítulo 16 enumera lo que le rompe algo a un consumidor: un campo eliminado, uno renombrado, un tipo cambiado, un parámetro obligatorio nuevo. Cada uno de ellos es visible como una diferencia entre dos documentos OpenAPI, y hay herramientas que comparan dos versiones y clasifican cada cambio como incompatible o no. Ejecuta una en el pipeline contra el documento de la rama principal, y un cambio incompatible no puede fusionarse por accidente. Solo puede fusionarse a propósito, con una versión nueva.
Así, la regla del Capítulo 16 deja de ser algo que los revisores tienen que recordar y pasa a ser algo que el pipeline impone.
Documenta los errores
La parte de una API que menos documentación recibe es aquella en la que los consumidores pasan más tiempo.
Para cada error, un consumidor necesita tres cosas: cómo reconocerlo, qué lo causó y qué hacer. Una tabla lo resuelve:
| Estado | code | Qué hacer |
|--------|--------|-----------|
| 400 | | La Idempotency-Key no es un UUID. Corrige el cliente |
| 401 | | Revisa el token. Puede haber caducado |
| 403 | | Al token le falta una habilidad. Pide uno que la tenga |
| 404 | | No existe, o no te corresponde verlo |
| 409 | request_in_progress | Reintenta tras los segundos de Retry-After |
| 409 | license_limit_reached | No reintentes. Elimina una licencia o pide un límite mayor |
| 422 | | Corrige los campos nombrados en errors. No reintentes sin cambios |
| 422 | | Sin errors: la clave de idempotencia ya se usó para una petición distinta |
| 429 | | Espera los segundos de Retry-After y reintenta |
| 502 | provider_failed | Es seguro reintentar con la misma clave de idempotencia |
| 502 | provider_rejected | Reintentar no ayudará. Ponte en contacto con soporte |
| 504 | provider_unavailable | Es seguro reintentar con la misma clave de idempotencia |
La última columna es la que la mayoría de la documentación omite, y la que ahorra una consulta a soporte.
Los valores de code salen del enum ErrorCode del Capítulo 7. Genera las filas de esta tabla a partir del enum, y no se podrá añadir un código a la API sin que aparezca en la documentación.