docs(api): add interactive OpenAPI reference

changelog.d/134-interactive-api-reference.md

@@ -0,0 +1,4 @@
+Adds a Scalar-powered interactive API reference and error catalogue to the
+VitePress docs site. The site sync validates and copies the generated
+OpenAPI document, and fails with a clear dependency message until issue
+#112 provides it. This PR is a draft pending that generator.

docs/api/README.md

@@ -1,12 +1,20 @@
 # API docs
 
+This table is a narrative overview. The generated OpenAPI document is the
+source for the [interactive API reference](https://docforum.github.io/docforum-core/api/interactive)
+and is validated and copied into the docs site at build time. Error codes
+are collected in the [API error catalogue](https://docforum.github.io/docforum-core/api/errors).
+
 Endpoints are grouped by module below. Which phases are built is tracked
 in `ROADMAP.md`, not here. Keep this file in sync with
 `backend/src/modules/*/routes` (AGENTS.md doc-update rule): when you add or
 change an endpoint, add or edit its row in that module's table, and leave
 the rest of the file alone.
 
-Base URL: `http://localhost:4000` locally (`PORT` in `.env`). No OpenAPI spec yet — TBD, tracked informally, not blocking Phase 1.
+Base URL: `http://localhost:4000` locally (`PORT` in `.env`). The OpenAPI
+generator is tracked by [issue #112](https://github.com/DocForum/docforum-core/issues/112);
+the docs-site integration depends on that generator and fails fast while the
+generated `backend/openapi.json` is absent or invalid.
 
 ## Health
 

docs/site/.gitignore

@@ -9,7 +9,13 @@ node_modules/
 /architecture/overview.md
 /architecture/essentials.md
 /architecture/adr/
-/api/
+!/api/
+/api/*
+!/api/interactive.md
+!/api/ApiReference.vue
+!/api/errors.md
+/api/reference.md
+/api/openapi.json
 /roadmap/
 /repos/web/readme.md
 /repos/web/architecture.md

docs/site/.vitepress/config.ts

@@ -70,7 +70,16 @@ export default defineConfig({
         },
       ],
 
-      '/api/': [{ text: 'API', items: [{ text: 'Reference', link: '/api/reference' }] }],
+      '/api/': [
+        {
+          text: 'API',
+          items: [
+            { text: 'Reference', link: '/api/reference' },
+            { text: 'Interactive reference', link: '/api/interactive' },
+            { text: 'Error catalogue', link: '/api/errors' },
+          ],
+        },
+      ],
 
       '/roadmap/': [
         {

docs/site/api/ApiReference.vue

@@ -0,0 +1,18 @@
+<script setup>
+import { ApiReference } from '@scalar/api-reference'
+import '@scalar/api-reference/style.css'
+import { withBase } from 'vitepress'
+
+const configuration = {
+  spec: { url: withBase('/api/openapi.json') },
+  hideTestRequestButton: true,
+  hideClientButton: true,
+  theme: 'default',
+}
+</script>
+
+<template>
+  <ClientOnly>
+    <ApiReference :configuration="configuration" />
+  </ClientOnly>
+</template>

docs/site/api/errors.md

@@ -0,0 +1,18 @@
+# API error catalogue
+
+Errors use a stable `code` in addition to the HTTP status and human-readable
+message. Clients should branch on `code`, not message text. The interactive
+reference is generated from the OpenAPI document; endpoint responses should
+link their documented error codes back to this catalogue.
+
+| Code | Status | Meaning |
+|---|---:|---|
+| [`EMAIL_NOT_VERIFIED`](./reference#email-verification-phase-8-issue-34) | 403 | Verify the account email before using a protected write endpoint. |
+| `INVALID_VERIFICATION_TOKEN` | 400 | The verification token is unknown, already used, or invalid. |
+| `VERIFICATION_TOKEN_EXPIRED` | 400 | Request a fresh verification email. |
+| `EMAIL_ALREADY_VERIFIED` | 409 | The account email is already verified. |
+| `EMAIL_VERIFICATION_RATE_LIMITED` | 429 | Wait for the resend interval before requesting another email. |
+
+This catalogue starts with the stable authentication and email-verification
+codes currently documented by the API. Add a row in the same change whenever
+a new public error code is introduced.

docs/site/api/interactive.md

@@ -0,0 +1,16 @@
+# Interactive API reference
+
+The reference below is rendered from the OpenAPI document generated from the
+API's route definitions. The docs sync step validates that document and stops
+the site build when it is missing or malformed, so a stale reference cannot
+be published accidentally.
+
+<ApiReference />
+
+Endpoint error codes are collected in the [API error catalogue](/api/errors).
+The reference is documentation only: request execution and API-client
+downloads are disabled.
+
+<script setup>
+import ApiReference from './ApiReference.vue'
+</script>