Swagger

This tutorial shows you how you can configure Swagger-ui with Ts.ED. Swagger uses the OpenApi to describe a Rest API. Ts.ED operates the existing decorators as well as new decorators to build a spec compliant with Swagger.

Installation

Run this command to install required dependencies by @tsed/swagger:

npm install --save @types/swagger-schema-official @tsed/swagger

Then add the following configuration in your Server:

import {Configuration} from "@tsed/common";
import "@tsed/platform-express";
import "@tsed/swagger"; // import swagger Ts.ED module

@Configuration({
  rootDir: __dirname,
  swagger: [
    {
      path: "/api-docs"
    }
  ]
})
export class Server {
}

The path option for Swagger will be used to expose the documentation (ex: http://localhost:8000/api-docs).

Normally, Swagger-ui is ready. You can start your server and check if it works fine.

Note: Ts.ED will print the swagger url in the console.

Swagger options

Some options are available to configure Swagger-ui, Ts.ED and the default spec information.

Key	Example	Description
path	/api-doc	The url subpath to access to the documentation.
doc	hidden-doc	The documentation key used by @Docs decorator to create several swagger documentations.
viewPath	${rootDir}/../views/swagger.ejs or false	The path to the ejs template. Set false to disabled swagger-ui.
cssPath	${rootDir}/spec/style.css	The path to the CSS file.
jsPath	${rootDir}/spec/main.js	The path to the JS file.
showExplorer	true	Display the search field in the navbar.
spec	{swagger: "2.0"}	The default information spec.
specPath	${rootDir}/spec/swagger.base.json	Load the base spec documentation from the specified path.
outFile	${rootDir}/spec/swagger.json	Write the swagger.json spec documentation on the specified path.
hidden	true	Hide the documentation in the dropdown explorer list.
options	Swagger-UI options	SwaggerUI options. See (https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/configuration.md)
operationIdFormat	%c.%m	Format of operationId field (%c: class name, %m: method name).

Multi documentations

It is also possible to create several swagger documentations with the doc option:

import {Configuration} from "@tsed/common";
import "@tsed/platform-express";
import "@tsed/swagger"; // import swagger Ts.ED module

@Configuration({
  rootDir: __dirname,
  swagger: [
    {
      path: "/api-docs-v1",
      doc: "api-v1"
    },
    {
      path: "/api-docs-v2",
      doc: "api-v2"
    }
  ]
})
export class Server {
}

Then use @Docs decorators on your controllers to specify where the controllers should be displayed.

import {Controller} from "@tsed/common";
import {Docs} from "@tsed/swagger";

@Controller("/calendars")
@Docs("api-v2") // display this controllers only for api-docs-v2
export class CalendarCtrlV2 {
}

// OR
@Controller("/calendars")
@Docs("api-v2", "api-v1")  // display this controllers for api-docs-v2 and api-docs-v1
export class CalendarCtrl {

}

Decorators

These decorators already add a documentation on Swagger:

• Header
• Status

In addition, the Ts.ED Swagger plugin gives some decorators to write documentation:

• Deprecated
• Consumes
• Docs
• Example
• Hidden
• Name
• Produces
• Responses
• Security
• Summary

Examples

Model documentation

One of the feature of Ts.ED is the model definition to serialize or deserialize a JSON Object (see converters section).

This model can be used on a method controller along with @BodyParams or other decorators.

import {Description, Example, Property, Title} from "@tsed/common";

export class CalendarModel {
  @Title("iD")
  @Description("Description of calendar model id")
  @Example("Description example")
  @Property()
  public id: string;

  @Property()
  public name: string;
}

Endpoint documentation

import {Description, BodyParams, Controller, Get, Post, QueryParams, Returns, ReturnsArray} from "@tsed/common";
import {Deprecated, Security, Summary} from "@tsed/swagger";
import {CalendarModel} from "./models/Calendar";

@Controller("/calendars")
export class Calendar {
  @Get("/:id")
  @Summary("Summary of this route")
  @Description("Return a calendar from the given id")
  @Returns(CalendarModel)
  @Returns(404, {description: "Not found"})
  async getCalendar(@Description("A calendar Id") @QueryParams() id: string): Promise<CalendarModel> {
    return {};
  }

  @Get("/")
  @Description("Return a list of Calendar")
  @ReturnsArray(CalendarModel)
  getCalendars(): Promise<CalendarModel[]> {
    return [];
  }

  @Get("/v0/:id")
  @Deprecated()
  @Description("Deprecated route, use /rest/calendars/:id instead of.")
  @Returns(CalendarModel)
  @Returns(404, {description: "Not found"})
  getCalendarDeprecated(@QueryParams("id") id: string): Promise<CalendarModel> {
    return {};
  }


  @Post("/")
  @Security("calendar_auth", "write:calendar", "read:calendar")
  @Returns(CalendarModel)
  async createCalendar(@BodyParams() body: any): Promise<CalendarModel> {
    return {};
  }
}

TIP

For endpoints returning an array you have to use the decorator instead of

WARNING

To update the swagger.json you have to reload the server before.

Import Javascript

It is possible to import a Javascript in the Swagger-ui documentation. This script lets you customize the swagger-ui instance.

import {Configuration} from "@tsed/common";
import "@tsed/platform-express";
import "@tsed/swagger"; // import swagger Ts.ED module

@Configuration({
  rootDir: __dirname,
  swagger: [
    {
      path: "/api-docs",
      jsPath: "/spec/main.js"
    }
  ]
})
export class Server {
}

In your JavaScript file, you can handle Swagger-ui configuration and the instance:

console.log(SwaggerUIBuilder.config); //Swagger-ui config

document.addEventListener('swagger.init', (evt) => {
    console.log(SwaggerUIBuilder.ui); //Swagger-ui instance
});

Credits

Thanks to vologab for his contribution.