tsoa-serverless v1.0.0

Documentation Generator

This command line utility generates documentation compliant with the (serverless-aws-documentation plugin)https://github.com/deliveryhero/serverless-aws-documentation from Swagger documentation generated by tsoa.

tsoa was originally designed to be used with express for an API with a single entrypoint, and outputs the swagger documentation compliant with OpenAPI 2.0 or 3.0. This package was designed to take the work done by that team, and extend it to be used with the serverless-aws-documentation plugin (which is not a direct 1-to-1 correlation with the OpenAPI specification) as well as an architecture which does not have a single entrypoint, but mutiple, such as a serverless architecture.

Tsoa

The tsoa library is a library which provides annotations for defining your API using TypeScript interfaces.

When tsoa generates swagger docs, it analyzes the handlers annotated with the @Route() annotation, as well as the inputs/outputs specified by the @Request(), @Path(), @Query(), @Header(), and @Response() annotations, and generates documentation based off the TypeScript interface provided to that annotation.

tsoa uses a tsoa.json configuration file, which must be specified in your handler directory. This tells tsoa where the entry point for the route is, where the IoC container is, as well as where the output the swagger docs that were generated for the API.

Usage

To use this tool, simply install serverless-tsoa either locally or globally, and run $(yarn bin)/document, or document respectively. You must have a tsoa.json file in each directory for the API you want documentation for in order for documentation to get generated for that handler.

Documentation generates individual serverless-aws-documentation compliant swagger docs in the handler directory, which can then be referenced in your serverless configuration. It also creates an OpenAPI 3.0 compliant swagger doc (with no transformations done) in the output directory specified.

By default, the source directory that contains your tsoa compliant TypeScript APIs will be set to the directory the command is run in, and the OpenAPI 3.0 compliant swagger docs generated will be outputted to the docs directory.

Configuration

Configuration can be specified in the root directory of a project in a file called documentationConfiguration with any of the following extensions, .yaml, .yml, .json, .js.

The configuration supported is as follows

{
  srcDir,
  outDir,
  config
}

This configuration can also be passed in via command line flags like so --srcDir=./ --outDir=./swagger

Caveats

1. tsoa has some limitations, such as refusing to generate documentation based on interface definitions in external packages. The rational behind this is that Swagger documentation is meant to be a contract between the API and their consumers; by using interface definitions in external packagaes that you do not control, you are potentially allowing that contract to change if the package gets updated. To avoid this, the tsoa development team suggests you create a local 'copy' of the external interface, with the minimally required attributes necessary for your API to function, rather than using the external package. That way, you have complete control over your API contract.

2. AWS can/will not properly parse objects directly specified as the request/response model. This will occur if you specify a class object as your request/response model in the tsoa annotations. You should abstract the parameters in that class out to an interface instead, and use that as your contract. This package will remove any unsupported object specs if they are generated by tsoa. AWS expects all request/response models to be defined as external references. So, this is not supported:

schema:
  additionalProperties: true
  type: object

but, this is:

schema:
  $ref: '#/components/schemas/ResponseObject'