tsed-openapi

# Ts.ED OpenAPI Ts.ED generates the OpenAPI document from the same `@tsed/schema` metadata that drives validation and serialization. Fix the metadata, never hand-edit the generated JSON. Read [the configuration reference](references/configuration.md) for every `swagger` / `scalar` option and [the decorator reference](references/decorators.md) for operation and response patterns. Model decorators belong to the sibling skill `tsed-models`; routes and parameters to `tsed-controllers`. ## 1. Install and register a UI 1. Install one or both UIs: `npm install @tsed/swagger` and/or `npm install @tsed/scalar`. 2. Import the package once in `Server.ts` for its side effect. Without the import the module is not registered and neither the UI nor the JSON route exists. 3. Declare `swagger` and/or `scalar` as an **array** of documents. ```typescript import "@tsed/platform-express"; import "@tsed/swagger"; import "@tsed/scalar"; import {Configuration} from "@tsed/di"; import * as rest from "./controllers/rest/index.js"; @Configuration({ mount: {"/rest": [...Object.values(rest)]}, swagger: [{path: "/doc", specVersion: "3.0.3"}], scalar: [{path: "/scalar", specVersion: "3.1.0"}] }) export class Server {} ``` - `mount` takes controller classes only (imported one by one or through a barrel as above). Do not pass glob strings: they are silently dropped, so the server and the spec expose no route. - The UI is served on `path`; the JSON on `<path>/<fileName>` (`swagger.json` for Swagger, `openapi.json` for Scalar). - `specVersion` accepts `"2.0"`, `"3.0.1"`, `"3.0.2"`, `"3.0.3"`, `"3.1.0"`. Always set it: when omitted (and `spec.openapi` is absent) Ts.ED emits Swagger `2.0`. - Do not give two documents the same `path`: the generated spec is cached by `path`. ## 2. Describe the document Put static metadata in `spec` and let controllers contribute paths and schemas. ```typescript swagger: [ { path: "/doc", specVersion: "3.0.3", spec: { info: {title: "Orders API", version: "1.2.0"}, components: { securitySchemes: {bearer: {type: "http", scheme: "bearer", bearerFormat: "JWT"}} } }, operationIdPattern: "%c_%m", sortPaths: true } ]; ``` - `info.version` falls back to the root `version` configuration key. - Use `operationIdPattern` (`%c` class name, `%m` method name) or `operationIdFormatter: (name, propertyKey, path) => string`. The default is camelCase of `%c.%m`; duplicates get a suffix. - Use `specPath` to merge a base JSON file, and the `$alterOpenSpec(spec, conf)` hook on `Server` for last-mile edits. ## 3. Document operations Import every decorator below from `@tsed/schema`. ```typescript import {Controller} from "@tsed/di"; import {NotFound} from "@tsed/exceptions"; import {PathParams} from "@tsed/platform-params"; import {Description, Get, Returns, Security, Summary, Tags} from "@tsed/schema"; import {Order} from "../models/Order.js"; @Controller("/orders") @Tags("Orders") export class OrdersController { @Get("/:id") @Summary("Get an order") @Description("Returns one order by its identifier") @Security("bearer") @(Returns(200, Order).Description("The order").Groups("read")) @(Returns(404, NotFound).Description("Order not found")) get(@PathParams("id") id: string) {} } ``` 1. Declare one `@Returns(status, Model)` per status code. Wrap chained calls in parentheses: `@(Returns(...).X())`. 2. Describe collections with `@(Returns(200, Array).Of(Order))`; a TypeScript `Promise<Order[]>` return type is not read. 3. Describe generics with `@Generics("T")` on the model and `.Of(Model)` / `.Nested(Model)` on the response. 4. Add `@Deprecated()`, `@OperationId("name")`, `@Consumes(...)`, `@Produces(...)` or `.ContentType(...)` only when the default is wrong. 5. Add examples on models with `@Example(value)`; on responses with `.Examples({...})`. 6. Every `@Security(name)` must match a key of `spec.components.securitySchemes` (OS3) or `spec.securityDefinitions` (OS2). ## 4. Split controllers across documents - By decorator: set `doc: "admin"` on a document and `@Docs("admin")` on controllers. Import `Docs` from `@tsed/swagger` or `@tsed/scalar`. - By route: set `pathPatterns: ["/rest/admin/**"]` (micromatch, negation with `!`). Patterns are tested against the controller's mounted route, not individual method paths. - A document with neither `doc` nor `pathPatterns` includes every non-hidden controller. A document with either one includes only matching controllers. - Use `@Hidden()` on a controller or a method to remove it from every document. ## 5. Export the spec without serving it Pick one; details and a full script in [the configuration reference](references/configuration.md#export-the-spec). 1. `outFile: "./spec/openapi.json"` on a document: written at `$onReady` on every start. 2. A script that calls `PlatformExpress.bootstrap(Server)` (no `listen()`), resolves `SwaggerService` from `@tsed/swagger` and calls `getOpenAPISpec(conf)`. 3. The Ts.ED CLI plugin `@tsed/cli-generate-swagger` (`tsed run generate-swagger --output <dir>`); see the sibling skill `tsed-cli`. 4. `getSpec(Controller)` or `generateSpec({tokens, ...})` from `@tsed/schema` for a DI-free unit test. ## 6. Diagnose a missing route or model Check in this order: 1. The UI package is imported in `Server.ts` and the configuration key is an array. 2. The controller is reachable from `mount` (or `imports`); the spec is built from mounted controllers only. 3. No `@Hidden()` on the class or method. 4. The document's `doc` / `pathPatterns` filter matches the controller (step 4). 5. The response has `@Returns(status, Model)`; without it the operation has no response schema. 6. Each model property carries a schema decorator (`@Property()`, `@Required()`, ...); undecorated properties are absent. 7. `.Groups(...)` on `@Returns` or `@Groups` on properties is not filtering the field out. 8. `disableSpec: true` removes the JSON route; `viewPath: false` removes the UI. ## Do not - Do not import decorators from `@tsed/common`; use `@tsed/schema`, `@tsed/di`, `@tsed/platform-params`. - Do not write `swagger: {...}` as an object; it must be an array. - Do not add `@Docs()` to some controllers and expect the others to stay in a document that sets `doc`. - Do not hand-write `paths` in `spec` for routes Ts.ED already serves; decorate the controller. - Do not expose the UI publicly by accident: gate the configuration by environment when the API is private. ## Pitfalls - A blank Swagger UI or Scalar page behind `helmet` is a CSP problem, not a spec problem. See https://tsed.dev/tutorials/swagger.md. - `hidden: true` on a Swagger document only hides it from the UI dropdown; the route stays served. - `outFile` is written after the server is ready, not at build time; a CI job needs option 2 or 3 of step 5. - `@Returns(Model)` without a status documents `200`. The second argument must be a class: write `@(Returns(404).Description("Not found"))`, not `@Returns(404, {description: "Not found"})`. - Scalar UI options go under `options`; `cdn` overrides the default jsDelivr bundle URL. - `SwaggerService` is an alias of `OpenAPIService` from `@tsed/openapi-utils`; `@tsed/scalar` does not re-export it. ## Checklist - The UI package is imported and `swagger` / `scalar` is an array with unique `path` values. - `spec.info` and security schemes are declared; every `@Security` name resolves. - Every operation has `@Summary`, and one `@Returns` per status code with a model. - Arrays and generics use `.Of()`; no response relies on the TypeScript return type. - Multi-document filters (`doc` + `@Docs`, or `pathPatterns`) were checked against the served JSON. - The exported spec was regenerated and diffed after the change. Further reading: https://tsed.dev/tutorials/swagger.md, https://tsed.dev/tutorials/scalar.md, https://tsed.dev/docs/controllers.md, https://tsed.dev/docs/model.md.