armar-swagger
(Repo back · desarrollo) Consolidar los fragmentos de Contrato OpenAPI que cada Tarea del tablero dejó escritos, en un único openapi.yaml del slice; correr Spectral (linter de OpenAPI) y publicar Swag
SKILL.mdback/.claude/skills/armar-swagger/SKILL.md
GitHubArmar swagger (backend)
Junta los fragmentos OpenAPI de las Tareas de un slice en un contrato único, lo valida y lo publica. No diseña la API (eso lo cerró cada Tarea): consolida, valida y expone.
Regla de oro
- NO INVENTAR endpoints ni campos. Si un fragmento está incompleto, se marca
⚠ pendientey se pregunta; no se completa por suposición. - Una sola fuente: el
openapi.yamlde la raíz del repo, versionado, que se consolida slice por slice (cada slice suma sus paths). - Un solo contrato: el servidor sirve ese mismo
openapi.yamlen/swagger, sin generar un segundo contrato a partir del código. Si el framework generara otro a partir de las anotaciones, habría dos contratos que pueden diferir: un endpoint o campo distinto entre el código y elopenapi.yamles un hallazgo. - Spectral manda: si el linter falla, el contrato no se da por bueno.
- Español (Argentina).
Flujo
- Reunir los fragmentos
paths:de las Tareas del slice (del contrato de cada Tarea). - Fusionar en
openapi.yaml(info + paths + components/schemas), sin duplicar. - Correr el linter de OpenAPI (Spectral) con el ruleset
bin/spectral-oas.yamldel repositorio del Cerebro; resolver hallazgos. - Publicar Swagger UI apuntando al yaml consolidado.
- Dejar el contrato como fuente: back lo valida/implementa, front lo simula a partir de él.
Entrada / Salida
- Entrada: fragmentos OpenAPI de las Tareas del slice.
- Salida:
openapi.yamlvalidado + Swagger UI navegable.
Barreras
- No agrega paths que ninguna Tarea especificó.
- Si dos Tareas definen el mismo endpoint distinto, es choque → se frena y se pregunta
(ese chequeo lo hace
analizar-tareasen el repo de conocimiento, antes de llegar acá).