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