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.