tsoa.json

Overview

The `tsoa.json` file serves as the central configuration for the **tsoa** framework within the project. **tsoa** is a TypeScript-oriented tool that facilitates the automatic generation of OpenAPI-compliant REST API specifications and routes based on TypeScript controllers and models.

This file defines key settings including the entry point of the application, controller file locations, OpenAPI specification output details, routing configuration, and ignore patterns for files/folders that should be excluded from tsoa processing. By customizing `tsoa.json`, developers control how tsoa scans the project for API controllers and how it generates API documentation and routing files.

Configuration Properties

Below is a detailed explanation of each property in the `tsoa.json` file, including purpose, expected value types, and usage:

Detailed Explanation of Properties

entryFile

• Type: string

• Example: "src/app.ts"

• Description:
  Defines the root file where the application starts, typically the main TypeScript file initializing the server or application. tsoa uses this as the base for importing and analyzing the project to find types and controllers.

noImplicitAdditionalProperties

• Type: "throw-on-extras" | "ignore" | "silently-remove-extras"

• Example: "throw-on-extras"

• Description:
  Controls how tsoa treats unexpected/extra properties in request bodies that do not map to the declared TypeScript models.

  • "throw-on-extras": Throws errors if extra properties are present.

  • "ignore": Allows extra properties without errors.

  • "silently-remove-extras": Strips out any extra properties silently.

controllerPathGlobs

• Type: string[]

• Example: ["src/**/controller.ts"]

• Description:
  Specifies the glob patterns to locate controller files. Controllers contain decorated classes and methods that expose API endpoints. This setting enables tsoa to find and process API interfaces.

spec

• Type: object

• Properties:

  • outputDirectory (string): Where the OpenAPI spec files are generated.

  • specVersion (number): Version of OpenAPI to generate. Usually 3 for OpenAPI 3.0.

• Example:

  "spec": {
    "outputDirectory": "src",
    "specVersion": 3
  }
  

• Description:
  Configures OpenAPI specification output. The specification files can be used for API documentation, client generation, or testing.

routes

• Type: object

• Properties:

  • routesDir (string): Directory where the tsoa-generated routing files will be saved.

• Example:

  "routes": {
    "routesDir": "src"
  }
  

• Description:
  Controls the output directory for route files that tsoa generates. These route files provide the glue between Express (or other frameworks) and the controller methods.

ignore

• Type: string[]

• Example: ["**/node_modules/**", "**/dist/**"]

• Description:
  File and folder glob patterns to exclude from tsoa processing. Commonly used to prevent scanning dependencies or build output folders.

Implementation Details and Usage Notes

• The configuration file is written in JSON format and must be valid JSON.

• Paths are relative to the root of the project.

• The controllerPathGlobs property typically points to files where API controllers are defined using tsoa decorators like @Route and @Get.

• The entryFile is essential as tsoa uses it to resolve types and dependencies.

• The OpenAPI spec version 3 allows you to leverage modern API specification features.

• The noImplicitAdditionalProperties setting enforces strict schema validation and helps improve API input validation.

• The generated spec files and route files are used at runtime (route files) and for API documentation or client generation (spec files).

• Typical workflow:

  1. Run tsoa CLI commands (tsoa spec and tsoa routes) which read this file.

  2. tsoa scans controllers and models according to the globs.

  3. tsoa generates OpenAPI spec and route files based on your code and this configuration.

  4. Generated files integrate into the app build/deployment.

Interactions with Other Parts of the System

• Source Controllers:
  The controllerPathGlobs points to controller files containing TypeScript classes decorated with tsoa decorators. These files define API endpoints and data types.

• Application Entry Point (entryFile):
  The entry file is the starting point for tsoa's type analysis and the main application bootstrap.

• Generated OpenAPI Spec:
  The spec files generated at the configured spec.outputDirectory are consumed by API documentation tools (like Swagger UI) or client SDK generators.

• Generated Routes:
  The route files generated in routes.routesDir are imported by the application server to wire controllers to HTTP endpoints dynamically.

• Build & Deployment:
  The ignore patterns prevent unnecessary files from being scanned, optimizing the build and generation process.

Example Usage Scenario

Assuming this `tsoa.json`, a typical command sequence might be:

tsoa spec       # Generates OpenAPI spec files in src/
tsoa routes     # Generates route files in src/

The application then imports generated routes from `src/routes.ts` (or similar), and the API spec can be served or displayed via Swagger UI.

Mermaid Diagram: Configuration Structure Flowchart

flowchart TD
    A[tsoa.json]
    A --> B(entryFile: src/app.ts)
    A --> C(noImplicitAdditionalProperties: throw-on-extras)
    A --> D(controllerPathGlobs: ["src/**/controller.ts"])
    A --> E(spec)
    E --> E1(outputDirectory: src)
    E --> E2(specVersion: 3)
    A --> F(routes)
    F --> F1(routesDir: src)
    A --> G(ignore: ["**/node_modules/**", "**/dist/**"])

Summary

The `tsoa.json` file is the cornerstone configuration that controls how tsoa processes your TypeScript project to generate API documentation and routes. It specifies where to find controllers, how to handle additional properties, where to output specs and routes, and which files to ignore. Proper configuration of this file ensures smooth integration of tsoa-generated API infrastructure into your project’s build and runtime environment.