Podrías escribir ese YAML a mano. Para una docena de endpoints llevaría una tarde. Y entonces tendría el problema que describió el Capítulo 14: exacto el día que lo escribiste, falso algún día posterior, y nadie podría decirte cuál.
Mira otra vez el fragmento. required: [name, domain]. maxLength: 100. Esos hechos ya los escribiste, en StoreLicenseRequest:
'name' => ['required', 'string', 'max:100'],
'domain' => ['required', 'string', 'max:100'],
Y la respuesta 201 es LicenseResource. La descripción de la API ya existe, en los dos lugares donde este libro te dijo que la pusieras. Un archivo OpenAPI escrito a mano es una segunda copia de información que ya tienes, y una segunda copia se desvía.
Así que genéralo a partir del código. La comunidad de Laravel tiene dos paquetes consolidados para esto. Scramble lee tus rutas, FormRequests y Resources, y produce un documento OpenAPI sin anotaciones en tu código. Scribe hace el mismo trabajo con otro enfoque y además puede llamar a tus endpoints para capturar respuestas de ejemplo. Los dos merecen una tarde de evaluación. Usaré como ejemplo el comportamiento de Scramble, tal como es en el momento de escribir esto:
composer require dedoc/scramble
Con eso instalado, la aplicación sirve un sitio de referencia en /docs/api y el documento mismo en /docs/api.json, que cubren todas las rutas bajo api. Fuera de tu entorno local las páginas están cerradas por defecto, detrás de un Gate llamado viewApiDocs que defines tú. No te fíes de la palabra de un paquete, ni de la mía: después de desplegar, pide las dos URL desde fuera y mira lo que vuelve. (Documentación de Laravel: Authorization › Gates.)
Por qué esto funciona para esta API
Un generador solo puede leer lo que está declarado. Esa es la recompensa de todo lo que hicieron los capítulos 2 y 5.
- La validación vive en FormRequests, así que el generador conoce cada campo, su tipo y sus límites. (Documentación de Laravel: Validation › Form Request Validation.)
- La salida pasa por Resources, así que conoce la forma de la respuesta. (Documentación de Laravel: Eloquent: API Resources.)
- Las rutas son de recurso, así que las rutas y los verbos siguen un patrón que reconoce.
- La autenticación es
auth:sanctum, así que sabe qué rutas necesitan un token.
Una API que valida dentro del controlador con sentencias if escritas a mano y devuelve arrays armados ahí mismo no le da a un generador nada que leer. Una versión anterior de esta API, con sus propias clases de respuesta envolviéndolo todo, habría necesitado una anotación en cada método para explicar lo que el framework ya no podía ver.
Es el mismo argumento del Capítulo 14, sobre las personas: quédate cerca del framework y un recién llegado ya conoce tus convenciones. Las herramientas también son recién llegadas.
Lo que sigues escribiendo tú
La generación te da la estructura. No puede darte el significado. Las palabras son tuyas:
- Una frase en cada endpoint que diga para qué sirve, no lo que hace. «Encola la licencia para su borrado en el proveedor. La licencia puede seguir visible en la lista durante un breve tiempo».
- La razón que hay detrás de una regla con la que un consumidor podría tropezar. Por qué un dominio está limitado a 100 caracteres es menos interesante que por qué un borrado responde 202.
- Las guías: primeros pasos, autenticación, reintentar de forma segura, paginación, versiones.
Los generadores leen los docblocks de los métodos de los controladores y las descripciones de las reglas, así que la mayor parte de esto vive en el código, junto a lo que describe, y cambia en el mismo pull request.