travetto: Swagger

Install: primary

$ npm install @travetto/swagger

In the Rest module, the controllers and endpoints can be described via decorators, comments, or typings. This only provides the general metadata internally. This is not sufficient to generate a usable API doc, and so this module exists to bridge that gap.

The module is provides a swagger v2 representation of the API metadata provided via the Rest and Schema modules.

Configuration

By installing the dependency, the swagger endpoint is automatically generated and exposed at the root of the application as /swagger.json.

All of the high level configurations can be found in the following structure:

Config: Swagger configuration

api:
  info:
    contact:
      email: <email, default package.json#author/email>
      name: <name, default package.json#author/name>
    description: <desc, default package.json#description>
    license: <license, default package.json#license>
    termsOfService?: <tos>
    title: <title, default package.json#name>
    version: <version, default package.json#version>
  host:
    basePath: <basePath, defaults to '/'>
    host?: <host name>
    swagger: <swagger version, only 2.0 is supported>
  client:
    codeGenImage: swaggerapi/swagger-codegen-cli
    output?: Codegen ouptut directory
    format?: Codegen language format
    formatOptions?: Options to pass to the codegen tool

Client Generation

In addition to the swagger JSON file generation, the module also supports generating a client via swagger-codegen-cli. This module integrates with the file watching paradigm and can regenerate the swagger client as changes to endpoints and models are made during development.