tsoa.json

Overview

The `tsoa.json` file is a configuration file used by **tsoa**, a TypeScript framework for building OpenAPI-compliant REST APIs and generating routes and swagger specifications automatically. This file defines the main settings and options for tsoa's code generation and runtime behavior in the project.

Specifically, it configures how tsoa should locate source files, generate API specifications, handle additional properties in models, configure routes, and exclude certain folders. This file is essential for integrating tsoa's automated workflow into the project's build and development process.

Detailed Explanation of Configuration Properties

Since `tsoa.json` is a JSON configuration file and does not contain classes or functions, this section explains all top-level properties and their meanings.

entryFile: string

• Description:
  Specifies the entry point of the application where tsoa starts parsing TypeScript files for controllers, models, and other API-related code.

• Value in this file: "src/index.ts"

• Usage:
  tsoa uses this file as the root from which it resolves imports and traces decorators that define API endpoints.

noImplicitAdditionalProperties: string

• Description:
  Controls how tsoa handles additional properties in model schemas that are not explicitly defined in the TypeScript interfaces/classes.

• Allowed values:

  • "silently-remove-extras" — silently strips extra properties from objects.

  • "throw-on-extras" — throws an error if extra properties are present.

  • "ignore" — allows additional properties without restrictions.

• Value in this file: "throw-on-extras"

• Usage:
  Setting this to "throw-on-extras" enforces strict validation on incoming payloads, ensuring no unexpected fields are accepted.

controllerPathGlobs: string[]

• Description:
  An array of glob patterns to locate controller files in the project. Controllers are files where routes and API endpoint methods are defined using tsoa decorators.

• Value in this file: ["src/**/controller.ts"]

• Usage:
  tsoa scans the matched files for controller classes decorated with @Route and @Get/@Post etc., to build the routing table and generate API specs.

spec: { outputDirectory: string, specVersion: number }

• Description:
  Configuration object for the OpenAPI specification generation.

• Properties:

  • outputDirectory (string): Folder where the generated OpenAPI JSON/YAML files should be saved.

  • specVersion (number): The OpenAPI version to generate. Currently supported: 2 or 3.

• Values in this file:

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

• Usage:
  tsoa will output the generated OpenAPI 3 specification files into the src directory.

routes: { routesDir: string }

• Description:
  Configuration for route generation.

• Properties:

  • routesDir (string): Directory where tsoa will generate the route files that define Express (or other framework) routes based on controllers.

• Value in this file:

  {
    "routesDir": "src"
  }
  

• Usage:
  tsoa will create route files in the src directory for use in the application runtime.

ignore: string[]

• Description:
  Array of glob patterns specifying files or directories to be excluded from tsoa's processing.

• Value in this file:

  ["**/node_modules/**", "**/dist/**"]
  

• Usage:
  These patterns prevent tsoa from scanning dependencies or build output folders, improving performance and avoiding conflicts.

Important Implementation Details and Algorithms

• Glob Patterns:
  The use of glob patterns ("src/**/controller.ts") enables flexible file discovery, allowing controllers to be placed in nested directories under src.

• Strict Validation via throw-on-extras:
  By throwing errors on additional properties, the API enforces strict schema validation, reducing bugs caused by unexpected data.

• Separation of Concerns:

  • spec handles API documentation generation.

  • routes handles server route generation.
    This clear separation aligns with best practices for API development.

• Output Locations:
  Both the generated OpenAPI spec and routes are output to the src directory, simplifying imports and deployment.

Interaction with Other Parts of the System

• Source Code:
  The entry file src/index.ts and all controllers matching src/**/controller.ts are parsed and processed by tsoa based on this configuration.

• Build Process:
  During build or development, tsoa reads this configuration to generate routes and OpenAPI specs, which are then used by the server and API documentation UI.

• Runtime:
  Generated route files in src are imported and used by the Express (or other) server to handle incoming HTTP requests.

• API Clients/Documentation:
  The OpenAPI spec generated into src is used to generate client SDKs or serve API docs (e.g., Swagger UI).

Usage Example

If you add a new controller at `src/user/controller.ts`, tsoa will automatically detect it due to the glob pattern `"src/**/controller.ts"`. When running tsoa commands (such as `tsoa routes` or `tsoa spec`), it will:

• Parse the UserController class and its methods.

• Generate route handlers in src/routes.ts (or similar).

• Update the OpenAPI spec JSON/YAML in src/.

Visual Diagram

Below is a flowchart illustrating the main configuration properties and their roles in the tsoa processing workflow:

flowchart TD
    A[tsoa.json Configuration]
    A --> B[entryFile: src/index.ts]
    A --> C[controllerPathGlobs: "src/**/controller.ts"]
    A --> D[noImplicitAdditionalProperties: "throw-on-extras"]
    A --> E[spec]
    A --> F[routes]
    A --> G[ignore]

    E --> E1[outputDirectory: src]
    E --> E2[specVersion: 3]

    F --> F1[routesDir: src]

    B --> H[Application Entry Point]
    C --> I[Controller Files]
    I --> J[Route Generation]
    J --> F1

    I --> K[OpenAPI Spec Generation]
    K --> E1

    D --> L[Validation Rules]
    L --> M[Strict Model Validation]

    G --> N[Excluded Paths]

Summary

The `tsoa.json` file is a critical configuration artifact for the tsoa framework, defining how the TypeScript API source code is parsed, how routes and OpenAPI specs are generated, and what validation rules are enforced. Proper configuration ensures seamless integration between code, API documentation, and runtime routes, enhancing developer productivity and API quality.