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

claude · claude · commit ca674a893724 · 2026-06-13T15:51:28.000Z
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
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -194,6 +194,13 @@ 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
+
       - name: Get git version info
         id: git_version
         run: scripts/get_version_info.sh github >> $GITHUB_OUTPUT
diff --git a/mise.dev.toml b/mise.dev.toml
@@ -41,9 +41,12 @@ 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
+"""
 
 [tasks."proto:clients"]
 description = "Generate Worker TS types and Flutter Dart client from OpenAPI spec"
diff --git a/web/_headers b/web/_headers
@@ -16,6 +16,15 @@
   Referrer-Policy: strict-origin-when-cross-origin
   Strict-Transport-Security: max-age=31536000; includeSubDomains
 
+# API docs — relaxed CSP to allow Redoc from jsDelivr CDN.
+# This path serves developer documentation, not the Flutter app.
+/api-docs/*
+  Content-Security-Policy: default-src 'self'; base-uri 'self'; frame-ancestors 'none'; object-src 'none'; script-src 'self' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; font-src 'self' data: https:; connect-src 'self'; worker-src 'self' blob:;
+  X-Content-Type-Options: nosniff
+  X-Frame-Options: DENY
+  Referrer-Policy: strict-origin-when-cross-origin
+  Strict-Transport-Security: max-age=31536000; includeSubDomains
+
 # Production Environment - Explicit domain rule for clarity
 # Custom domain: cambeerfestival.app
 # Path-based rules below apply to this domain for performance optimization
diff --git a/web/api-docs/.gitignore b/web/api-docs/.gitignore
@@ -0,0 +1,2 @@
+# Generated in CI (build-web job) and locally via: MISE_ENV=dev ./bin/mise run proto:generate
+openapi.yaml
diff --git a/web/api-docs/index.html b/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="https://cdn.jsdelivr.net/npm/redoc@2.4.0/bundles/redoc.standalone.js"></script>
+  </body>
+</html>

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+# Generated in CI (build-web job) and locally via: MISE_ENV=dev ./bin/mise run proto:generate`
	`2`	`+openapi.yaml`