docs(api): publish MyFestival OpenAPI spec via Redoc at /api-docs/ (#428)

* docs(api): publish MyFestival OpenAPI spec via Redoc at /api-docs/

Adds a Redoc-rendered API docs page at /api-docs/ in the Cloudflare Pages
deployment. The OpenAPI spec is generated from proto at build time (not
committed), consistent with the proto-in-CI pattern from #426.

- web/api-docs/index.html: Redoc page loading openapi.yaml from jsDelivr CDN
- web/api-docs/.gitignore: openapi.yaml is generated, not committed
- web/_headers: /api-docs/* CSP override allowing cdn.jsdelivr.net for Redoc
- ci.yml build-web: buf generate + copy openapi.yaml before flutter build
- mise.dev.toml proto:generate: also copies to web/api-docs/ for local dev

https://claude.ai/code/session_015uTnGiC56cEELZMH2cQQU4

* docs: add API docs link to README

https://claude.ai/code/session_015uTnGiC56cEELZMH2cQQU4

* fix(api-docs): exempt /api-docs/ from Flutter SPA catch-all rewrite

Cloudflare Pages does not resolve implicit directory indexes before
evaluating _redirects rewrite rules, so /api-docs/ was being caught by
/* /index.html 200 before the Redoc page could be served.

Adding explicit /api-docs and /api-docs/ rules before the catch-all
routes those two paths to /api-docs/index.html directly.

https://claude.ai/code/session_015uTnGiC56cEELZMH2cQQU4

* fix(api-docs): serve Redoc from self rather than CDN to avoid CSP issues

Downloading redoc.standalone.js at build time (CI) and local dev
(proto:generate) so it is served from 'self', which the existing
Flutter CSP already allows. Removes the /api-docs/* CSP override
that was added to permit cdn.jsdelivr.net.

https://claude.ai/code/session_015uTnGiC56cEELZMH2cQQU4

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: richardthe3rd

.github/workflows/ci.yml

@@ -194,6 +194,14 @@ jobs:
         with:
           google-services-json: ${{ secrets.GOOGLE_SERVICES_JSON }}
 
+      - name: Generate OpenAPI spec from proto
+        uses: bufbuild/buf-action@v1
+        with:
+          setup_only: true
+      - run: cd proto && buf generate
+      - run: cp docs/code/api/openapi/openapi.yaml web/api-docs/openapi.yaml
+      - run: curl -sLo web/api-docs/redoc.standalone.js https://cdn.jsdelivr.net/npm/redoc@2.4.0/bundles/redoc.standalone.js
+
       - name: Get git version info
         id: git_version
         run: scripts/get_version_info.sh github >> $GITHUB_OUTPUT

README.md

@@ -14,6 +14,7 @@ A Flutter app for browsing beers, ciders, meads, and more at the Cambridge Beer
 **Production**: [cambeerfestival.app](https://cambeerfestival.app)
 **Staging**: [staging.cambeerfestival.app](https://staging.cambeerfestival.app)
 **Android**: [Google Play](https://play.google.com/store/apps/details?id=ralcock.cbf)
+**API docs**: [cambeerfestival.app/api-docs](https://cambeerfestival.app/api-docs/)
 
 ## Features
 

mise.dev.toml

@@ -41,9 +41,13 @@ dir = "proto"
 run = "buf dep update"
 
 [tasks."proto:generate"]
-description = "Generate OpenAPI from the proto contract (BSR remote plugin)"
+description = "Generate OpenAPI from the proto contract (BSR remote plugin), then sync to web/api-docs/"
 dir = "proto"
-run = "buf generate"
+run = """
+buf generate
+cp ../docs/code/api/openapi/openapi.yaml ../web/api-docs/openapi.yaml
+curl -sLo ../web/api-docs/redoc.standalone.js https://cdn.jsdelivr.net/npm/redoc@2.4.0/bundles/redoc.standalone.js
+"""
 
 [tasks."proto:clients"]
 description = "Generate Worker TS types and Flutter Dart client from OpenAPI spec"

web/_redirects

@@ -2,4 +2,10 @@
 # Redirect to festival drinks list — these URLs were never shared publicly
 /:festivalId/drink/:id /:festivalId 302
 
+# API docs — serve the Redoc page before the Flutter SPA catch-all intercepts it.
+# Cloudflare Pages doesn't resolve implicit directory indexes before checking
+# rewrite rules, so /api-docs/ would otherwise match /* below.
+/api-docs /api-docs/index.html 200
+/api-docs/ /api-docs/index.html 200
+
 /* /index.html 200

web/api-docs/.gitignore

@@ -0,0 +1,3 @@
+# Generated in CI (build-web job) and locally via: MISE_ENV=dev ./bin/mise run proto:generate
+openapi.yaml
+redoc.standalone.js

web/api-docs/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Cambridge Beer Festival — MyFestival API</title>
+    <link rel="icon" type="image/png" href="../favicon.png" />
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <redoc
+      spec-url="openapi.yaml"
+      expand-responses="200"
+      required-props-first="true"
+    ></redoc>
+    <script src="redoc.standalone.js"></script>
+  </body>
+</html>