Generating Routes and OAS
Relevant API reference: Config, generateRoutes, generateSpec, generateSpecAndRoutes, ExtendedRoutesConfig, and ExtendedSpecConfig.
Using CLI
Basic Commands
Use tsoa --version to print the installed CLI version, and tsoa --help or tsoa <command> --help to view available commands and options. Invalid commands, unsupported options, and missing option values exit with an error. When an option is repeated, its last value is used.
# generate OAS
tsoa spec
# generate routes
tsoa routes
# generate both with an explicit config
tsoa spec-and-routes -c tsoa.json
# discover configs and update only stale route and OpenAPI outputs
tsoa generate
# fail when generated outputs are stale without writing files
tsoa check
# check a configured custom route template without writing generated files
tsoa template-check
# discover config files beneath the current directory
tsoa discover
# discover config files beneath a path or glob
tsoa discover "packages/*"The CLI resolves configuration for the requested output. tsoa spec does not require route integrations. tsoa routes validates specification settings when selected controllers expose @SpecPath, or when a custom template or route generator needs the existing specification context. Built-in routes without specification serving can proceed independently of unused specification output settings. Commands generating both outputs validate both requirements.
Options
OpenAPI Specification (OAS) generation
Usage: tsoa spec [options]
Options:
--configuration, -c tsoa configuration file; default is tsoa.json in the working directory [string]
--discover discover tsoa config files using a path or glob before running the command [string]
--host API host [string]
--basePath Base API path [string]
--yaml Write the OpenAPI spec as YAML [boolean]
--json Write the OpenAPI spec as JSON (takes precedence over --yaml) [boolean]Route generation
Usage: tsoa routes [options]
Options:
--configuration, -c tsoa configuration file; default is tsoa.json in the working directory [string]
--discover discover tsoa config files using a path or glob before running the command [string]
--basePath Base API path [string]Custom template validation
Set routes.middlewareTemplate to the template you are authoring, then run:
tsoa template-check
tsoa template-check --configuration path/to/tsoa.json
# -c is an alias for --configuration.The command reads and parses the selected Handlebars template, renders it with the real selected controller metadata and existing route context, then checks the rendered TypeScript syntax in memory. It uses the usual configuration formats and defaults. It exits successfully when these checks pass and reports the selected template and original cause when they fail. Read and parse failures are reported before controller metadata is constructed.
Template parser locations refer to the template. TypeScript diagnostics explicitly identify the virtual generated output and its line and column; those positions are not template locations. No generated routes or specifications are written, and custom route generators and controller code are not executed.
This checks syntax and rendering for the selected context. It does not type-check generated code against your application, resolve generated imports, validate runtime behavior, or exercise template branches that the selected context does not render. Ordinary route generation continues to support custom templates producing arbitrary output; template-check explicitly expects TypeScript output.
Config discovery
Usage: tsoa discover [pathOrGlob]discoversearches beneath the provided path, or beneath the current working directory when no argument is provided.- Glob inputs are supported, so commands like
tsoa discover "packages/*"ortsoa spec --discover "services/*"will expand matching roots first. - Discovery recognizes these conventional config filenames:
tsoa.jsontsoa.yamltsoa.ymltsoa.config.jstsoa.config.cjs
spec,routes, andspec-and-routescan fan out across all discovered configs:
tsoa spec --discover "packages/*"
tsoa routes --discover "./services"
tsoa spec-and-routes --discover .Change-aware generation and CI checks
generate and check discover conventional tsoa config files automatically. Both commands search beneath the current working directory by default, or beneath an optional path or glob:
# Generate routes and OpenAPI specs for every discovered config.
# Existing files are written only when their generated content changed.
tsoa generate
tsoa generate "services/*"
# Compare generated content with the files on disk without creating directories
# or writing files. The command exits non-zero when any output is missing or stale.
tsoa check
tsoa check "services/*"Each discovered config used by these combined commands must include both spec and routes sections. check reports the stale output paths and suggests running tsoa generate, which makes it suitable as a pull request CI gate.
Because config discovery is automatic, generate and check ignore the --configuration (-c) and --discover options and print a warning when either is supplied. Use the optional [pathOrGlob] argument to limit discovery instead.
Change-aware generation cannot safely control file writes performed by a custom routes.routeGenerator, so generate and check reject those configs. The existing routes and spec-and-routes commands continue to support custom route generators.
You can find the Reference for the tsoa configuration file here
For information on the configuration object (tsoa.json), you may also be interested in:
Programmatic
Import programmatic generation APIs from tsoa-next/cli. The root tsoa-next entrypoint is runtime-only and should be used for decorators and runtime helpers.
import { generateRoutes, generateSpec, generateSpecAndRoutes, ExtendedRoutesConfig, ExtendedSpecConfig } from 'tsoa-next/cli'
;(async () => {
const specOptions: ExtendedSpecConfig = {
basePath: '/api',
entryFile: './api/server.ts',
specVersion: 3,
outputDirectory: './api/dist',
controllerPathGlobs: ['./routeControllers/**/*Controller.ts'],
}
const routeOptions: ExtendedRoutesConfig = {
basePath: '/api',
entryFile: './api/server.ts',
routesDir: './api',
}
await generateSpec(specOptions)
await generateRoutes(routeOptions)
// Or generate both outputs from one shared metadata pass:
await generateSpecAndRoutes({
configuration: {
entryFile: './api/server.ts',
controllerPathGlobs: ['./routeControllers/**/*Controller.ts'],
spec: {
outputDirectory: './api/dist',
specVersion: 3.1,
},
routes: {
routesDir: './api',
},
},
})
})()Note: If you use tsoa programmatically, please be aware that tsoa's methods can (under rare circumstances) change in minor and patch releases. But if you are using tsoa in a .ts file, then TypeScript will help you migrate to any changes. We reserve this right to change what are essentially our internal methods so that we can continue to provide incremental value to the majority user (our CLI users). The CLI however will only receive breaking changes during a major release.
Contributors
Vanna DiCatania