()
| 15 | * at GET /admin/openapi.json for downstream tooling. |
| 16 | */ |
| 17 | export const generateAdminDefinition = (): any => ({ |
| 18 | openapi: OPENAPI_VERSION, |
| 19 | info: { |
| 20 | title: 'Etherpad Admin API', |
| 21 | description: |
| 22 | 'Authenticated administrative endpoints consumed by the Etherpad admin UI. ' + |
| 23 | 'Distinct from the public /api/{version}/* surface served by /api/openapi.json. ' + |
| 24 | 'For completeness this document also includes non-admin endpoints that are ' + |
| 25 | 'consumed by the pad UI itself (e.g. /api/version-status) since they share the ' + |
| 26 | 'same internal route registration.', |
| 27 | version: getEpVersion(), |
| 28 | }, |
| 29 | paths: { |
| 30 | '/admin-auth/': { |
| 31 | post: { |
| 32 | operationId: 'verifyAdminAccess', |
| 33 | summary: 'Verify or establish an admin session', |
| 34 | description: |
| 35 | 'POST with `Authorization: Basic <user:pass>` to log in as an admin ' + |
| 36 | '(server sets a session cookie on success). POST with no auth header ' + |
| 37 | 'to verify an existing admin session cookie. The response body is ' + |
| 38 | 'always empty; the status code conveys the outcome.', |
| 39 | security: [ |
| 40 | {basicAuth: []}, |
| 41 | {sessionCookie: []}, |
| 42 | {}, |
| 43 | ], |
| 44 | responses: { |
| 45 | '200': {description: 'Caller is an authenticated admin.'}, |
| 46 | '401': {description: 'No authentication presented and no admin session exists.'}, |
| 47 | '403': {description: 'Authenticated, but the user is not an admin.'}, |
| 48 | }, |
| 49 | }, |
| 50 | }, |
| 51 | '/api/version-status': { |
| 52 | get: { |
| 53 | operationId: 'getVersionStatus', |
| 54 | summary: 'Outdated-version notice signal for the pad UI', |
| 55 | description: |
| 56 | 'Returns a non-null `outdated` value only to the first author of the supplied pad, ' + |
| 57 | 'and only when the running server is at least one minor version behind the latest ' + |
| 58 | 'published release. Result is cached per (padId, authorId) for 60 s.', |
| 59 | parameters: [ |
| 60 | { |
| 61 | name: 'padId', |
| 62 | in: 'query', |
| 63 | required: false, |
| 64 | schema: {type: 'string'}, |
| 65 | description: |
| 66 | 'Pad whose first-author membership is being checked. ' + |
| 67 | 'Omitted padId always yields a null result.', |
| 68 | }, |
| 69 | ], |
| 70 | responses: { |
| 71 | '200': { |
| 72 | description: 'Outdated-notice signal.', |
| 73 | content: { |
| 74 | 'application/json': { |
no test coverage detected