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 for every swagger / scalar option and the decorator reference 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.

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.

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.

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.

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.