swagger

internal/api/swagger

Embeds the Swagger UI 5.x distribution and the longue-vue OpenAPI spec, and exposes two HTTP handlers used by cmd/longue-vue:

• UIHandler() — serves the Swagger UI shell (HTML + JS/CSS assets) from index.html (our bootstrap) and dist/ (vendored upstream).
• OpenAPISpecHandler() — serves the embedded openapi.yaml.

Source of truth for the spec lives at api/openapi/openapi.yaml. The copy under this package is generated by make swagger-sync and enforced by make swagger-sync-check in CI.

Upgrading Swagger UI

1. Pick the latest stable 5.x release from https://github.com/swagger-api/swagger-ui/releases.
2. Download the tarball:

   curl -L https://github.com/swagger-api/swagger-ui/archive/refs/tags/v<TAG>.tar.gz \
     -o /tmp/swagger-ui.tar.gz
   

3. Extract and copy the five files we use into dist/:

   tar -xzf /tmp/swagger-ui.tar.gz -C /tmp
   SRC=/tmp/swagger-ui-<TAG>/dist
   cp "$SRC/swagger-ui-bundle.js"            internal/api/swagger/dist/
   cp "$SRC/swagger-ui-standalone-preset.js" internal/api/swagger/dist/
   cp "$SRC/swagger-ui.css"                  internal/api/swagger/dist/
   cp "$SRC/favicon-16x16.png"              internal/api/swagger/dist/
   cp "$SRC/favicon-32x32.png"              internal/api/swagger/dist/
   

   Do not copy upstream index.html; ours lives in the parent dir.
4. Update dist/.version:

   swagger-ui-<TAG>
   <one-line change summary, e.g. "CVE-2025-xxxx fix">
   

5. Run make test and verify "Try it out" works against a local server.
6. Commit.

Why our index.html is outside dist/

Keeping the vendor surface pristine makes upgrades a straight directory replacement with no patch to re-apply. The bootstrap (index.html) lives one level up.