Status

@tsed/schema

Usage

import { Status } from "@tsed/schema";

See /packages/specs/schema/src/types/decorators/operations/status.ts.

Overview

function Status(status: string | number, model?: Type<any> | any): ReturnsChainedDecorators;

Description

Add responses documentation for a specific status code.

Usage

Ts.ED v6 API introducing the chaining decorator concept. Now a decorator like Returns can be used with another decorators like Description.

import {Returns} from "@tsed/schema";

@Controller("/")
class MyController {
  @Status(404, String).Description("Not Found")
  @Status(200, Model).Description("Success")
  async myMethod(): Promise<Model> {}
}

TIP

TypeScript and your IDE will discover automatically the chained decorators. But for more details you can look on ReturnsChainedDecorators interface, to know what chained decorators are available under Returns decorator.

This example will produce this documentation in swagger:

{
  "responses": {
    "404": {
      "description": "Description",
      "schema": {"type": "string"}
    },
    "2OO": {
      "description": "Description",
      "schema": {"$ref": "..."}
    }
  }
}

Declaring a generic model

Sometime, it might be useful to use generic models. TypeScript doesn't store the generic type in the metadata. This is why we need to explicitly the generic models with the decorators.

One of the generic's usage, can be a paginated list. With Returns decorator it's now possible to generic type and generate the appropriate OpenSpec documentation.

Starting with the pagination model, by using Generics and CollectionOf:

@Generics("T")
class Pagination<T> {
 @CollectionOf("T")
 data: T[];

 @Property()
 totalCount: number;
}

Now, we need a model to be used with the generic Pagination model:

class Product {
 @Property()
 id: string;

 @Property()
 title: string;
}

Finally, we can use our models on a method as following:

class Controller {
  @OperationPath("POST", "/")
  @Status(200, Pagination).Of(Product).Description("description")
  async method(): Promise<Pagination<Product> | null> {
    return null;
  }
}

Declaring a nested generics models 6+

It's also possible to a nested generics models in order to have this type Pagination<Submission<Product>>:

import {Post, Generics, Property, Returns} from "@tsed/schema";

class Controller {
  @Post("/")
  @Status(200, Pagination).Of(Submission).Nested(Product).Description("description")
  async method(): Promise<Pagination<Submission<Product>> | null> {
    return null;
  }
}

And here is the Submission model:

import {Generics, Property} from "@tsed/schema";

@Generics("T")
class Submission<T> {
  @Property()
  _id: string;
  @Property("T")
  data: T;
}