Feat/openapi docs

[evanjacobson]

Summary

Usage analytics did not have a reviewer-friendly public OpenAPI surface, which made the available tRPC endpoints and their intended roles harder to understand from generated docs.

This adds an allowlisted Swagger/OpenAPI docs surface for the usage analytics tRPC endpoints, including shared schemas, bearer auth metadata, static Swagger UI assets, and clearer endpoint descriptions that distinguish summary cards, trends, breakdown charts, and detailed table/export usage. The implementation follows the existing explicit registry/schema pattern so only intentionally documented procedures are exposed.

Lower-level notes

• Serves the OpenAPI JSON at /api/openapi.json and Swagger UI at /api/docs.
• Copies pinned Swagger UI assets into ignored generated public assets during web dev/build/prepare flows.
• Keeps usage analytics Zod schemas reusable between the router and OpenAPI document generation.

Verification

• verified Swagger and Swagger UI load locally

Visual Changes

Reviewer Notes

Focus areas: the allowlist boundary for documented tRPC procedures, CSP/static asset handling for Swagger UI, and whether the endpoint role descriptions are clear enough for API consumers.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (5 files)

• apps/web/src/lib/openapi/trpc-openapi.test.ts
• apps/web/src/lib/openapi/trpc-openapi.ts
• apps/web/src/lib/openapi/trpc-registry.ts
• apps/web/src/lib/trpc/init.ts
• apps/web/src/lib/trpc/transport.ts

Previous Review Summaries (4 snapshots, latest commit 6ac7944)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 6ac7944)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (4 files)

• apps/web/src/app/api/docs/route.test.ts
• apps/web/src/app/api/docs/route.ts
• apps/web/src/lib/openapi/trpc-openapi.test.ts
• apps/web/src/lib/openapi/trpc-openapi.ts

Previous review (commit 2c9e71c)

Status: 1 Issue Found | Recommendation: Address before merge

Fix these issues in Kilo Cloud

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/openapi/trpc-openapi.ts	76	Strips bearer auth requirements from protected OpenAPI operations

Files Reviewed (5 files)

• apps/web/src/app/api/docs/route.test.ts - 0 issues
• apps/web/src/app/api/docs/route.ts - 0 issues
• apps/web/src/lib/openapi/trpc-openapi.test.ts - 0 issues
• apps/web/src/lib/openapi/trpc-openapi.ts - 1 issue
• apps/web/src/lib/openapi/trpc-registry.ts - 0 issues

Previous review (commit 34b8b50)

Status: 1 Issue Found | Recommendation: Address before merge

Fix these issues in Kilo Cloud

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/app/api/docs/route.ts	69	Hides only the top-bar auth wrapper, not operation-level auth controls

Files Reviewed (14 files)

• .gitignore - 0 issues
• apps/web/next.config.mjs - 0 issues
• apps/web/package.json - 0 issues
• apps/web/scripts/copy-swagger-ui-assets.mjs - 0 issues
• apps/web/src/app/api/docs/route.test.ts - 0 issues
• apps/web/src/app/api/docs/route.ts - 1 issue
• apps/web/src/app/api/openapi.json/route.ts - 0 issues
• apps/web/src/lib/openapi/trpc-openapi.test.ts - 0 issues
• apps/web/src/lib/openapi/trpc-openapi.ts - 0 issues
• apps/web/src/lib/openapi/trpc-registry.ts - 0 issues
• apps/web/src/routers/usage-analytics-router.ts - 0 issues
• apps/web/src/routers/usage-analytics-schemas.ts - 0 issues
• pnpm-workspace.yaml - 0 issues
• scripts/prepare.sh - 0 issues

Previous review (commit eb6be61)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (13 files)

• .gitignore
• apps/web/next.config.mjs
• apps/web/package.json
• apps/web/scripts/copy-swagger-ui-assets.mjs
• apps/web/src/app/api/docs/route.ts
• apps/web/src/app/api/openapi.json/route.ts
• apps/web/src/lib/openapi/trpc-openapi.test.ts
• apps/web/src/lib/openapi/trpc-openapi.ts
• apps/web/src/lib/openapi/trpc-registry.ts
• apps/web/src/routers/usage-analytics-router.ts
• apps/web/src/routers/usage-analytics-schemas.ts
• pnpm-workspace.yaml
• scripts/prepare.sh

---

_{Reviewed by gpt-5.4-20260305 · Input: 85.5K · Output: 11.4K · Cached: 584.2K}

_{Review guidance: REVIEW.md from base branch main}