mirror of https://github.com/OpenVidu/openvidu.git
76 lines
3.7 KiB
Markdown
76 lines
3.7 KiB
Markdown
# 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."
|