mirror of https://github.com/OpenVidu/openvidu.git
openvidu-dashboard: archive openapi-reference, keep only the specs
juancarmore
parent
0a27846ecf
commit
322781dd73
|
|
@ -1,2 +0,0 @@
|
|||
schema: spec-driven
|
||||
created: 2026-10-27
|
||||
|
|
@ -1,124 +0,0 @@
|
|||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
- `RouteRegistry` holds one `RouteDefinition` per route, and `openApiDocument(registry, version)`
|
||||
(`src/api/openapi.ts`) turns the listed routes into a zod-openapi 6 document.
|
||||
- How the generator fills error responses today:
|
||||
- It adds `400` to every operation, `401` to every non-public one, and `403` "PRO feature on CE" to every PRO route.
|
||||
No document lists those routes in an edition that answers that 403: locks are left out in CE, and PRO never
|
||||
answers it.
|
||||
- It adds the `ApiError` schema only to the errors it adds itself. Errors a route declares (login `401`/`429`,
|
||||
`ready` `503`, analytics `403`, detail `404`) have no body.
|
||||
- Parameter descriptions come from `.meta()` on the Zod schemas:
|
||||
- A `.meta()` placed before `.default()` stays inside the parameter's schema and never reaches the parameter object.
|
||||
This is why `from` and `to` show no description.
|
||||
- `csvParam()` parses a string, so its parameters render as plain strings.
|
||||
- `DashboardOptions` carries the edition and version. The public base path is bound to `TOKENS.BasePath` by a CE
|
||||
startup hook, before the docs router is built.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- A document that a client generator and a reader can use as is.
|
||||
- Pieces that let PRO document its routes the same way, without CE knowing them.
|
||||
- Tests that keep the invariants for every route, not only for today's.
|
||||
|
||||
**Non-Goals:**
|
||||
- Changing requests, responses, status codes or authentication.
|
||||
- Serving the document in production.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Explicit `operationId`, checked by the registry
|
||||
|
||||
- `RouteDefinition` gains a required `operationId`, camelCase, verb first:
|
||||
- `list<Resources>` for paged lists;
|
||||
- `get<Resource>` for single documents;
|
||||
- `get<Resource><Sub>` for sub-resources and summaries;
|
||||
- `login`, `refreshSession`, `logout`, `getCurrentAdmin` for auth;
|
||||
- `getHealth`, `getReadiness` for the probes.
|
||||
- `register()` and `replace()` throw on an `operationId` another route already uses. A lock has none and is never
|
||||
listed.
|
||||
|
||||
Rejected: deriving IDs from method and path. Names such as `getApiV1RoomsSidSeries` read badly, and they would change
|
||||
when a path changes.
|
||||
|
||||
### Declared tags
|
||||
|
||||
- `registry.tag(name, description)` declares a tag. Each route module declares its tags before registering its
|
||||
routes.
|
||||
- `register()` throws on an undeclared tag.
|
||||
- The document lists the declared tags, in declaration order, that at least one listed operation uses.
|
||||
- Tag names are Title Case nouns: `Probes`, `Auth`, `Info`, `Overview`, `Rooms`, `Participants`, `Agents`, `Egress`,
|
||||
`Ingress`, `Analytics`, `Status`.
|
||||
- PRO declares its own tags (such as `Tracks`) the same way.
|
||||
|
||||
### Error responses built by the generator
|
||||
|
||||
- `400` (`Invalid request`) is added only when the route has params, a query or a body.
|
||||
- `401` is added for `bearer` and `optional-bearer` routes.
|
||||
- The automatic `403` for PRO routes is removed.
|
||||
- Every response with status ≥ 400 gets `application/json` with `ApiError` when the route gives no schema.
|
||||
- `RouteResponse` gains `edition?: Edition`. A response with an edition is left out of other editions' documents. The
|
||||
CE analytics routes mark their `PRO_FEATURE` `403` as `ce`. The registry exposes its edition for this.
|
||||
|
||||
### Parameters
|
||||
|
||||
- **Shared pieces in `query.ts`:**
|
||||
- Shared parameters carry their descriptions after `.default()`, so zod-openapi lifts them to the parameter: `from`,
|
||||
`to`, `tz`, `limit`, `order`, `cursor` and `q`.
|
||||
- `to` gets its own example (`now`).
|
||||
- **`csvParam(values)`:** adds `param: { style: 'form', explode: false }` and
|
||||
`override: { type: 'array', items: { type: 'string', enum: values } }`. The route adds the description. The other
|
||||
comma-separated parameters do the same: `features`, the egress `status` with its `all`, and the analytics `metrics`
|
||||
and `dimensions`.
|
||||
- **`If-None-Match`:** the generator adds this header parameter to every operation whose responses include `304`.
|
||||
- **Integration test:** it asserts that every parameter of the booted document has a description. A new route without
|
||||
one fails CI instead of silently degrading the document.
|
||||
|
||||
Alternatives rejected for the list parameters:
|
||||
- Changing their schemas to `z.array()` with `explode`: Express parses `a,b` as one string, so validation would change.
|
||||
- A document-wide `override` hook keyed on the transform: too implicit.
|
||||
|
||||
### Refresh cookie and `Set-Cookie`
|
||||
|
||||
- `RouteDefinition` gains an optional `refreshCookie: 'required' | 'optional'`. It only affects the document;
|
||||
authentication is unchanged, and the auth routes stay `public`.
|
||||
- The generator adds the `refreshCookie` security scheme (`apiKey`, `in: cookie`, name `REFRESH_COOKIE`). It sets
|
||||
`security: [{ refreshCookie: [] }]` for refresh, and `[{}, { refreshCookie: [] }]` for logout, which also answers
|
||||
without a cookie.
|
||||
- The auth responses that set or clear the cookie declare a `Set-Cookie` header with its attributes: login `200`,
|
||||
refresh `200` and `401`, logout `204`.
|
||||
|
||||
### Metadata
|
||||
|
||||
- `openApiDocument(registry, { version, basePath, license? })`:
|
||||
- `servers: [{ url: basePath without its trailing slash, or '/' }]`;
|
||||
- `info.description`: one Markdown text of the conventions, edition-neutral;
|
||||
- `info.license`: the given one, or `{ name: 'Apache 2.0', identifier: 'Apache-2.0' }`.
|
||||
- `DashboardOptions` gains an optional `apiLicense`, which an extending edition passes. CE passes nothing.
|
||||
|
||||
### Schema with required keys never defined
|
||||
|
||||
`byInputType: z.record(inputType, count)` renders `required` without `properties`. It becomes
|
||||
`z.object({ rtmp: count, whip: count, url: count })`, which validates the same values.
|
||||
|
||||
### Unknown-route message
|
||||
|
||||
`apiNotFound` is mounted on `/api`, so `req.path` lacks the prefix. The message uses the path of `req.originalUrl`
|
||||
(without the query string), which is the path the client sent: `${req.baseUrl}${req.path}` would turn `/api` into
|
||||
`/api/`.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Breaking for PRO at compile time]** `operationId` becomes required, and undeclared tags throw. → PRO adds them in
|
||||
the same move of `ce.ref`, with its own document test.
|
||||
- **[`override` drifting from the parser]** The array rendering duplicates the allowed values. → Both come from the same
|
||||
`values` argument of `csvParam()`. The other list parameters pass their own enum constant to both the parser and the
|
||||
override.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
This changes the document only; deploy as usual. Clients that generated code from the old document get stable method
|
||||
names from now on.
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
The OpenAPI document (`GET /api/v1/docs/openapi.json`) lists every route, but it does not describe the API well enough
|
||||
to use it without reading the code:
|
||||
- No operation has an `operationId`.
|
||||
- Most parameters have no description.
|
||||
- Comma-separated lists are typed as bare strings.
|
||||
- Several error responses are missing or have no body schema.
|
||||
- Some responses are declared that the edition never answers.
|
||||
- There is no `servers`, `license` or tag list.
|
||||
|
||||
The unknown-route `404` also names a path without its `/api` prefix.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Document metadata:**
|
||||
- `info` gains a description of the API conventions (authentication, time ranges, pagination, errors, conditional
|
||||
requests, request IDs, versioning) and the license.
|
||||
- `servers` gains the public base path.
|
||||
- A `tags` list, with one description per tag, in a stable order.
|
||||
- **Operations:**
|
||||
- Every operation has a unique `operationId` and tags from that list.
|
||||
- Every parameter has a description.
|
||||
- Comma-separated list parameters are documented as arrays of their allowed values (`style: form`, `explode: false`).
|
||||
- Routes answered conditionally declare the `If-None-Match` request header next to their `ETag` and `304`.
|
||||
- The auth routes declare the refresh cookie they read (as a cookie security scheme) and the `Set-Cookie` header they
|
||||
send.
|
||||
- **Error responses:**
|
||||
- Every error response an operation can answer is declared with the `ApiError` schema.
|
||||
- `400` is declared only for operations that take input.
|
||||
- A response that only one edition answers appears only in that edition's document. This covers the automatic
|
||||
`PRO_FEATURE` `403`, which no listed route answers, and the `403` of PRO metrics on the CE analytics routes.
|
||||
- **Schemas:** the ingress summary's `byInputType` is a plain object with its three keys. It was a record that
|
||||
required keys it never defined.
|
||||
- **404 message:** the unknown-route `404` message names the full request path, `No API route for GET
|
||||
/api/v1/does-not-exist`.
|
||||
|
||||
Scope excludes the following:
|
||||
- No route, parameter or response body changes.
|
||||
- The PRO routes are documented by the PRO workspace on top of the generic pieces this change adds, so CE needs no
|
||||
PRO-specific code, and the seams stay generic: an optional license for the document and the per-route fields.
|
||||
|
||||
Edition: CE, and the generic pieces PRO builds on. Repository: `OpenVidu/openvidu` (dashboard) only.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
None.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `api-conventions`:
|
||||
- The OpenAPI document gains requirements on its metadata, operations, parameters and error responses.
|
||||
- The unknown-route scenario fixes its message.
|
||||
|
||||
## Impact
|
||||
|
||||
- Backend:
|
||||
- `src/api/openapi.ts` (generator).
|
||||
- `src/api/route-registry.ts` (`operationId`, tag declarations, per-response edition, refresh cookie field).
|
||||
- `src/api/query.ts` (shared parameter descriptions and the array form of `csvParam`).
|
||||
- Every `src/*/*-routes.ts` (operation IDs, tags, parameter descriptions, error responses).
|
||||
- `src/ingress/ingress-responses.ts`.
|
||||
- `src/http/errors.ts`.
|
||||
- `src/lifecycle/startup.ts` (base path, and an optional license from `DashboardOptions`).
|
||||
- Tests: unit tests of the generator and the registry, and an integration test that checks the invariants above on the
|
||||
document of the booted CE dashboard.
|
||||
- PRO: its own routes must supply `operationId`, declared tags and parameter descriptions. That is a compile-time
|
||||
requirement once it moves `ce.ref`.
|
||||
- CHANGELOG (`CHANGELOG.md`, 3.10.0, Added › Data), a new line: "API reference outside production: an OpenAPI 3.1
|
||||
document at `/api/v1/docs/openapi.json` and a browsable page at `/api/v1/docs`, with operation IDs, described
|
||||
parameters and every error response."
|
||||
|
|
@ -1,110 +0,0 @@
|
|||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Base path and resource naming
|
||||
|
||||
Edition: CE. Every dashboard API route SHALL live under `/api/v1`, use lower-case plural nouns for resources
|
||||
(`rooms`, `participants`, `agents`, `tracks`, `egresses`, `ingresses`, `analytics`, `overview`, `status`, `auth`,
|
||||
`info`), nest
|
||||
sub-resources at most one level under the parent identifier, and answer every unknown `/api` path with a JSON
|
||||
`404` instead of the SPA fallback.
|
||||
|
||||
#### Scenario: Sub-resource path
|
||||
|
||||
- **GIVEN** a room with SID `RM_abc`
|
||||
- **WHEN** the client requests its participants
|
||||
- **THEN** the path is `GET /api/v1/rooms/RM_abc/participants`
|
||||
|
||||
#### Scenario: Unknown API path
|
||||
|
||||
- **WHEN** the client requests `GET /api/v1/does-not-exist` or `GET /api/anything`
|
||||
- **THEN** the response is `404` with body `{ error: { code: 'NOT_FOUND', message } }` and
|
||||
`Content-Type: application/json`, never the SPA `index.html`, and the message names the full path, such as
|
||||
`No API route for GET /api/v1/does-not-exist`
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: OpenAPI document metadata
|
||||
|
||||
Edition: CE. The OpenAPI document SHALL carry the following:
|
||||
- an `info.description` of the API conventions;
|
||||
- `info.license`: Apache 2.0 unless the edition provides another;
|
||||
- one `servers` entry with the dashboard's public base path;
|
||||
- a `tags` list with a description per tag, holding only the tags of the listed operations.
|
||||
|
||||
#### Scenario: Behind a base path
|
||||
|
||||
- **GIVEN** the server runs with `DASHBOARD_BASE_PATH=/dashboard/` and `NODE_ENV=development`
|
||||
- **WHEN** the client reads the document
|
||||
- **THEN** `servers[0].url` is `/dashboard`, and the paths start with `/api/v1`
|
||||
|
||||
#### Scenario: Conventions described
|
||||
|
||||
- **WHEN** the client reads `info.description`
|
||||
- **THEN** it explains the following:
|
||||
- the bearer access token and the refresh cookie;
|
||||
- the `from`, `to` and `tz` time expressions;
|
||||
- cursor pagination with `limit` and `total`;
|
||||
- the `ApiError` envelope;
|
||||
- `ETag` and `If-None-Match`;
|
||||
- the `X-Request-Id` header;
|
||||
- the versioning policy.
|
||||
|
||||
#### Scenario: Tags
|
||||
|
||||
- **WHEN** the client reads `tags`
|
||||
- **THEN** every operation's tags are listed there with a description, and no listed tag lacks an operation
|
||||
|
||||
### Requirement: OpenAPI operations
|
||||
|
||||
Edition: CE. Every operation of the OpenAPI document SHALL have the following:
|
||||
- a unique `operationId`, a summary and tags;
|
||||
- a description for every parameter, with comma-separated list parameters as arrays of their allowed values
|
||||
(`style: form`, `explode: false`);
|
||||
- an `If-None-Match` header parameter when it can answer `304`;
|
||||
- on the auth routes, the refresh cookie as a cookie security scheme, and the `Set-Cookie` header of the responses that
|
||||
set or clear it.
|
||||
|
||||
#### Scenario: Operation identifiers
|
||||
|
||||
- **WHEN** the client reads every operation of the document
|
||||
- **THEN** each has an `operationId` that no other operation shares, such as `listRooms` for `GET /api/v1/rooms`
|
||||
|
||||
#### Scenario: List parameter
|
||||
|
||||
- **WHEN** the client reads the `kind` parameter of `GET /api/v1/participants`
|
||||
- **THEN** it has a description, `style: form`, `explode: false`, and an array schema whose items enumerate the
|
||||
participant kinds
|
||||
|
||||
#### Scenario: Conditional request
|
||||
|
||||
- **WHEN** the client reads `GET /api/v1/overview`
|
||||
- **THEN** it declares the `If-None-Match` header parameter, the `ETag` header of its `200`, and its `304`
|
||||
|
||||
#### Scenario: Refresh cookie
|
||||
|
||||
- **WHEN** the client reads `POST /api/v1/auth/refresh`
|
||||
- **THEN** its security names the refresh cookie scheme (`in: cookie`, `name: ov_dashboard_refresh`), and its `200` and
|
||||
`401` declare `Set-Cookie`
|
||||
|
||||
### Requirement: OpenAPI error responses
|
||||
|
||||
Edition: CE. Every error response an operation can answer SHALL be declared with the `ApiError` schema. This means
|
||||
`400` only for operations that take parameters or a body, `401` for operations that need or accept a token, and the
|
||||
route's own errors such as `404`, `429` and `503`. A response that only one edition answers SHALL appear only in that
|
||||
edition's document.
|
||||
|
||||
#### Scenario: Operation without input
|
||||
|
||||
- **WHEN** the client reads `GET /api/v1/health`
|
||||
- **THEN** it declares no `400`
|
||||
|
||||
#### Scenario: Error body
|
||||
|
||||
- **WHEN** the client reads the `429` of `POST /api/v1/auth/login`
|
||||
- **THEN** its content is `application/json` with the `ApiError` schema
|
||||
|
||||
#### Scenario: Edition-specific error
|
||||
|
||||
- **WHEN** the client reads `GET /api/v1/analytics/series` in the CE document
|
||||
- **THEN** it declares the `403` of a PRO metric, dimension or node scope; and no CE operation declares a `403`
|
||||
`PRO_FEATURE` for being a PRO route
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
# Tasks
|
||||
|
||||
## 1. Backend: registry and generator
|
||||
|
||||
- [x] 1.1 In `src/api/route-registry.ts`, add:
|
||||
- a required `operationId` and an optional `refreshCookie: 'required' | 'optional'` to `RouteDefinition`;
|
||||
- `edition?: Edition` to `RouteResponse`;
|
||||
- `tag(name, description)` and the `edition` getter to `RouteRegistry`.
|
||||
`register()` and `replace()` reject a repeated `operationId` and an undeclared tag. Verify with
|
||||
`route-registry.test.ts` cases for both rejections.
|
||||
- [x] 1.2 In `src/api/openapi.ts`, change `openApiDocument(registry, { version, basePath, license? })` to emit:
|
||||
- `servers`, `info.description`, `info.license` and `tags` (declared and used, in declaration order);
|
||||
- `operationId`;
|
||||
- `400` only with input, `401` for `bearer` and `optional-bearer`, no automatic `403`;
|
||||
- `ApiError` on every error without a schema;
|
||||
- responses filtered by `edition`;
|
||||
- the `If-None-Match` parameter on operations with `304`;
|
||||
- the `refreshCookie` security scheme;
|
||||
and drop the dead locked-route description. Verify with `route-registry.test.ts` cases for each rule.
|
||||
- [x] 1.3 In `src/lifecycle/startup.ts` and `src/index.ts`, add the optional `DashboardOptions.apiLicense` and pass it,
|
||||
with the bound base path, to the document. Verify with the typecheck and the `servers` case of 1.2.
|
||||
|
||||
## 2. Backend: parameters and routes
|
||||
|
||||
- [x] 2.1 In `src/api/query.ts`, describe `from`, `to`, `tz`, `limit`, `order`, `cursor` and `q` at the parameter
|
||||
level (after `.default()`), with `to` getting its own example. Make `csvParam()` render as an array of its values
|
||||
with `style: form`, `explode: false`. Verify with a generator unit case on a ranged list query.
|
||||
- [x] 2.2 In every `src/*/*-routes.ts` and `src/api/probes.ts`:
|
||||
- declare the module's tags;
|
||||
- give each route its `operationId`;
|
||||
- describe every route-specific parameter;
|
||||
- render the other comma-separated parameters as arrays (`features`, egress `status`, analytics `metrics` and
|
||||
`dimensions`);
|
||||
- mark the analytics `403` as `edition: 'ce'`;
|
||||
- add `refreshCookie` and the `Set-Cookie` headers to the auth routes.
|
||||
Verify with the integration test of 3.1.
|
||||
- [x] 2.3 In `src/ingress/ingress-responses.ts`, make `byInputType` a `z.object` with `rtmp`, `whip` and `url`. Verify
|
||||
with the ingress response unit tests and the mapper checks.
|
||||
- [x] 2.4 In `src/http/errors.ts`, make `apiNotFound` name the path of `req.originalUrl`. Verify with the app unit test
|
||||
of the unknown API path, which asserts the message.
|
||||
|
||||
## 3. Tests and docs
|
||||
|
||||
- [x] 3.1 Add the integration test `test/integration/openapi-document.test.ts`. It boots the CE dashboard in
|
||||
development and reads `/api/v1/docs/openapi.json`, then asserts:
|
||||
- unique `operationId`s;
|
||||
- every tag is declared with a description;
|
||||
- every parameter has a description;
|
||||
- every response ≥ 400 has `ApiError`;
|
||||
- no `400` on operations without input;
|
||||
- no `403` `PRO_FEATURE` outside the analytics routes;
|
||||
- `If-None-Match` wherever there is a `304`;
|
||||
- the refresh cookie scheme on refresh and logout;
|
||||
- `servers` and `license`.
|
||||
Verify that `./dashboard.sh test-integration` passes.
|
||||
- [x] 3.2 Lint both a development document and the generated one with Redocly CLI (`recommended`, scratch install,
|
||||
not a dependency). Expect no errors, and no warnings other than intentional ones recorded in this file. Verify by
|
||||
running it by hand once.
|
||||
Result: valid. The only warnings are `operation-4xx-response` on `getHealth`, `getReadiness` and `logout`, which
|
||||
answer no 4xx by design.
|
||||
- [x] 3.3 Update `dashboard-ce/backend/AGENTS.md` (route declaration: `operationId`, tags through `registry.tag`,
|
||||
parameter descriptions, response `edition`, `refreshCookie`), and add the `CHANGELOG.md` line of the proposal.
|
||||
Verify that `./dashboard.sh check` passes.
|
||||
|
||||
## Workflow follow-up
|
||||
|
||||
- Move `ce.ref` in openvidu-pro and document the PRO routes there (PRO change).
|
||||
- Archive when the owner asks.
|
||||
|
|
@ -25,7 +25,8 @@ sub-resources at most one level under the parent identifier, and answer every un
|
|||
|
||||
- **WHEN** the client requests `GET /api/v1/does-not-exist` or `GET /api/anything`
|
||||
- **THEN** the response is `404` with body `{ error: { code: 'NOT_FOUND', message } }` and
|
||||
`Content-Type: application/json`, never the SPA `index.html`
|
||||
`Content-Type: application/json`, never the SPA `index.html`, and the message names the full path, such as
|
||||
`No API route for GET /api/v1/does-not-exist`
|
||||
|
||||
### Requirement: JSON field conventions
|
||||
|
||||
|
|
@ -583,3 +584,89 @@ omit `stale` otherwise, also when it has no `lastStatsAt`.
|
|||
- **GIVEN** a closed room whose `lastStatsAt` is 2 hours old
|
||||
- **WHEN** it is returned
|
||||
- **THEN** it has no `stale` property
|
||||
|
||||
### Requirement: OpenAPI document metadata
|
||||
|
||||
Edition: CE. The OpenAPI document SHALL carry the following:
|
||||
- an `info.description` of the API conventions;
|
||||
- `info.license`: Apache 2.0 unless the edition provides another;
|
||||
- one `servers` entry with the dashboard's public base path;
|
||||
- a `tags` list with a description per tag, holding only the tags of the listed operations.
|
||||
|
||||
#### Scenario: Behind a base path
|
||||
|
||||
- **GIVEN** the server runs with `DASHBOARD_BASE_PATH=/dashboard/` and `NODE_ENV=development`
|
||||
- **WHEN** the client reads the document
|
||||
- **THEN** `servers[0].url` is `/dashboard`, and the paths start with `/api/v1`
|
||||
|
||||
#### Scenario: Conventions described
|
||||
|
||||
- **WHEN** the client reads `info.description`
|
||||
- **THEN** it explains the following:
|
||||
- the bearer access token and the refresh cookie;
|
||||
- the `from`, `to` and `tz` time expressions;
|
||||
- cursor pagination with `limit` and `total`;
|
||||
- the `ApiError` envelope;
|
||||
- `ETag` and `If-None-Match`;
|
||||
- the `X-Request-Id` header;
|
||||
- the versioning policy.
|
||||
|
||||
#### Scenario: Tags
|
||||
|
||||
- **WHEN** the client reads `tags`
|
||||
- **THEN** every operation's tags are listed there with a description, and no listed tag lacks an operation
|
||||
|
||||
### Requirement: OpenAPI operations
|
||||
|
||||
Edition: CE. Every operation of the OpenAPI document SHALL have the following:
|
||||
- a unique `operationId`, a summary and tags;
|
||||
- a description for every parameter, with comma-separated list parameters as arrays of their allowed values
|
||||
(`style: form`, `explode: false`);
|
||||
- an `If-None-Match` header parameter when it can answer `304`;
|
||||
- on the auth routes, the refresh cookie as a cookie security scheme, and the `Set-Cookie` header of the responses that
|
||||
set or clear it.
|
||||
|
||||
#### Scenario: Operation identifiers
|
||||
|
||||
- **WHEN** the client reads every operation of the document
|
||||
- **THEN** each has an `operationId` that no other operation shares, such as `listRooms` for `GET /api/v1/rooms`
|
||||
|
||||
#### Scenario: List parameter
|
||||
|
||||
- **WHEN** the client reads the `kind` parameter of `GET /api/v1/participants`
|
||||
- **THEN** it has a description, `style: form`, `explode: false`, and an array schema whose items enumerate the
|
||||
participant kinds
|
||||
|
||||
#### Scenario: Conditional request
|
||||
|
||||
- **WHEN** the client reads `GET /api/v1/overview`
|
||||
- **THEN** it declares the `If-None-Match` header parameter, the `ETag` header of its `200`, and its `304`
|
||||
|
||||
#### Scenario: Refresh cookie
|
||||
|
||||
- **WHEN** the client reads `POST /api/v1/auth/refresh`
|
||||
- **THEN** its security names the refresh cookie scheme (`in: cookie`, `name: ov_dashboard_refresh`), and its `200` and
|
||||
`401` declare `Set-Cookie`
|
||||
|
||||
### Requirement: OpenAPI error responses
|
||||
|
||||
Edition: CE. Every error response an operation can answer SHALL be declared with the `ApiError` schema. This means
|
||||
`400` only for operations that take parameters or a body, `401` for operations that need or accept a token, and the
|
||||
route's own errors such as `404`, `429` and `503`. A response that only one edition answers SHALL appear only in that
|
||||
edition's document.
|
||||
|
||||
#### Scenario: Operation without input
|
||||
|
||||
- **WHEN** the client reads `GET /api/v1/health`
|
||||
- **THEN** it declares no `400`
|
||||
|
||||
#### Scenario: Error body
|
||||
|
||||
- **WHEN** the client reads the `429` of `POST /api/v1/auth/login`
|
||||
- **THEN** its content is `application/json` with the `ApiError` schema
|
||||
|
||||
#### Scenario: Edition-specific error
|
||||
|
||||
- **WHEN** the client reads `GET /api/v1/analytics/series` in the CE document
|
||||
- **THEN** it declares the `403` of a PRO metric, dimension or node scope; and no CE operation declares a `403`
|
||||
`PRO_FEATURE` for being a PRO route
|
||||
|
|
|
|||
Loading…
Reference in New Issue