docs(openapi): document apikey auth in openapi.json

[JohnMcLear]

Fixes #7532.

Summary

• The API accepts the key via ?apikey=, ?api_key=, and the apikey header, but only ?apikey= was advertised in /api-docs.json.
• /api/{version}/openapi.json was worse: it hardcoded an OAuth2 (openid) scheme even when Etherpad was started in apikey auth mode, so the doc contradicted how the server actually authenticated.
• Both generators now key securitySchemes / security off settings.authenticationMethod. When it's apikey, they publish three schemes: apikey in query, api_key in query (alias), and apikey in header.
• openapi.ts regenerates the definition per request so runtime settings are reflected (it used to cache at startup).

The raw authorization: <key> header still works in code but is deliberately not documented — pinning it in the spec would ossify a quirk.

Test plan

• New mocha specs in src/tests/backend/specs/api/api.ts verify /api-docs.json exposes all three schemes and /api/openapi.json exposes an apiKey scheme when authenticationMethod === 'apikey'.
• pnpm ts-check clean.
• Existing api.ts specs still pass.
• CI green.

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Document API key authentication methods in OpenAPI specifications

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Document all three API key authentication methods in OpenAPI specs
  - Query parameter apikey (primary)
  - Query parameter api_key (alias)
  - Header apikey
• Switch security scheme generation based on authenticationMethod setting
• Regenerate OpenAPI definitions per request to reflect runtime settings
• Add comprehensive test coverage for apikey authentication documentation

Diagram

flowchart LR
  A["authenticationMethod setting"] -->|apikey mode| B["Generate apiKey schemes"]
  A -->|sso mode| C["Generate OAuth2 scheme"]
  B --> D["Query: apikey"]
  B --> E["Query: api_key"]
  B --> F["Header: apikey"]
  C --> G["OpenID Connect"]
  D --> H["/api-docs.json"]
  E --> H
  F --> H
  D --> I["/api/openapi.json"]
  E --> I
  F --> I
  G --> H
  G --> I
  J["Per-request regeneration"] --> H
  J --> I

Loading

File Changes

1. src/node/handler/RestAPI.ts ✨ Enhancement +23/-3

Add multiple API key authentication schemes

• Added apiKeyAlias scheme for api_key query parameter
• Added apiKeyHeader scheme for apikey header parameter
• Updated security array to include all three apiKey variants when `authenticationMethod ===
 'apikey'`
• Maintains backward compatibility with existing apiKey scheme for apikey query parameter

src/node/handler/RestAPI.ts

---

2. src/node/hooks/express/openapi.ts ✨ Enhancement +42/-21

Make OpenAPI definitions dynamic and authentication-aware

• Replaced hardcoded OAuth2 scheme with conditional logic based on authenticationMethod
• Added three apiKey schemes (apiKey, apiKeyAlias, apiKeyHeader) for apikey mode
• Changed endpoint handlers to regenerate definitions per request instead of caching at startup
• Ensures runtime settings changes are reflected in OpenAPI documentation

src/node/hooks/express/openapi.ts

---

3. src/tests/backend/specs/api/api.ts 🧪 Tests +58/-0

Add tests for API key authentication documentation

• Added new test suite for apikey authentication documentation
• Verifies /api-docs.json exposes all three apiKey schemes
• Verifies /api/openapi.json exposes apiKey security in apikey mode
• Tests both primary apikey and alias api_key query parameters
• Tests apikey header parameter

src/tests/backend/specs/api/api.ts

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

Looking for bugs?

Check back in a few minutes. An AI review agent is analyzing this pull request.

[TomNewChao]

Well done

[JohnMcLear]

@copilot address qodos concerns and fix the PR

[Copilot]

@copilot address qodos concerns and fix the PR

Fixed in 71d8fdf. The main issue was that apiKeyAlias and apiKeyHeader were unconditionally included in securitySchemes even when authenticationMethod is 'sso'. They're now added dynamically inside the apikey branch (matching the pattern used for the sso scheme), and marked as optional in the TypeScript type annotation so they're only present in the spec when actually applicable.