tsoa.json

Overview

The `tsoa.json` file is a configuration file used by **tsoa**, a popular TypeScript framework that automatically generates OpenAPI (Swagger) specifications and routes based on TypeScript controllers and models. This file defines key settings for how tsoa scans, processes, and outputs API metadata and routes for the project.

Specifically, it configures:

• The entry point file for the API.

• How to handle additional properties in models.

• The glob pattern to locate controller files.

• Output directories and OpenAPI specification version.

• Routes directory location.

• Files and directories to ignore during the scanning process.

This configuration is essential for integrating tsoa into the build and development workflow, enabling automatic API documentation generation and route wiring based on TypeScript code annotations.

Detailed Explanation of Configuration Properties

1. entryFile: string

• Description:
  Specifies the main entry file of the application that tsoa uses as a starting point to resolve the project structure and type information.

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

• Usage:
  tsoa begins processing from this file to understand the API structure.

2. noImplicitAdditionalProperties: string

• Description:
  Controls how tsoa handles additional properties in request and response models that are not explicitly defined in the TypeScript interfaces or classes.

• Possible values:

  • "throw-on-extras": Throws an error if extra properties are found during validation.

  • "silently-remove-extras": Removes extra properties without error.

  • "ignore": Allows extra properties without validation errors.

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

• Usage:
  Enforces strict model validation by preventing unexpected properties, improving API reliability and security.

3. controllerPathGlobs: string[]

• Description:
  An array of glob patterns that tells tsoa where to find controller files containing API route handlers.

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

• Usage:
  tsoa scans all files matching the pattern to build the API routes and documentation.

4. spec: object

• Description:
  Configuration for the OpenAPI specification generation.

• Properties:

  • outputDirectory: string
    Directory where the generated OpenAPI spec JSON or YAML files will be saved.

  • specVersion: number
    The OpenAPI version to generate (commonly 2 for Swagger 2.0, or 3 for OpenAPI 3.0+).

• Values in this file:

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

• Usage:
  Controls where and in which format the API documentation is generated.

5. routes: object

• Description:
  Configuration related to the generation of routes files that map OpenAPI operations to controller methods.

• Properties:

  • routesDir: string
    Directory where the generated route files will be placed.

• Value in this file:

  {
    "routesDir": "src"
  }
  

• Usage:
  Helps tsoa know where to output the routes that are later imported in the application.

6. ignore: string[]

• Description:
  An array of glob patterns specifying files and directories to exclude from tsoa scanning.

• Value in this file:
  ["**/node_modules/**", "**/dist/**"]

• Usage:
  Prevents unnecessary scanning of dependencies and build artifacts, speeding up the generation process and avoiding conflicts.

Usage Example

Given this configuration, when you run tsoa commands like `tsoa spec` or `tsoa routes`, the tool will:

1. Start from src/app.ts.

2. Search all files matching src/**/controller.ts.

3. Generate OpenAPI 3.0 specification JSON files inside the src directory.

4. Generate routes files inside the src directory.

5. Throw an error if request/response models contain unexpected extra properties.

6. Ignore files in node_modules and dist folders.

Important Implementation Details

• Strict Property Validation:
  The "throw-on-extras" setting enforces that the API strictly conforms to defined TypeScript models, reducing runtime errors and security issues caused by unexpected data.

• Glob Pattern Matching:
  Using glob patterns (controllerPathGlobs and ignore) allows flexible and fine-grained control over which files tsoa processes, supporting modular project structures.

• Separation of Spec and Routes Output:
  Spec and routes generation can be independently configured, allowing customized build pipelines.

Interaction with Other Parts of the System

• Controllers:
  The controllers located via controllerPathGlobs contain decorators that tsoa reads to generate API specs and route handlers.

• Entry File (src/app.ts):
  This file typically sets up the Express or similar server, importing the generated routes to serve HTTP requests.

• Generated API Documentation:
  The OpenAPI spec generated in the spec.outputDirectory is used for API documentation, client SDK generation, and testing tools.

• Build System:
  This configuration is often referenced in package.json scripts or build tools (e.g., npm scripts, webpack) to automate generation during development or deployment.

Visual Diagram

Below is a flowchart representing how `tsoa.json` configures the workflow of tsoa tool within the project:

flowchart TD
    A[Start: Run tsoa command] --> B[Read tsoa.json]
    B --> C{Locate Entry File}
    C --> D[src/app.ts]
    B --> E{Find Controllers}
    E --> F[Files matching "src/**/controller.ts"]
    B --> G[Ignore files: node_modules, dist]
    B --> H[Set Validation Mode: throw-on-extras]
    B --> I[Set Spec Output Directory: src]
    B --> J[Set Routes Output Directory: src]
    D --> K[Analyze TypeScript Types]
    F --> K
    K --> L[Generate OpenAPI Spec (v3)]
    K --> M[Generate Routes]
    L --> N[Save spec files in src/]
    M --> O[Save routes files in src/]
    N --> P[Use Spec for Docs, SDKs]
    O --> Q[Import routes in app.ts]

Summary

The `tsoa.json` file is a crucial configuration point for the tsoa framework, specifying how API routes and documentation are generated from TypeScript source code. It defines entry points, file scanning rules, validation strictness, and output locations for specs and routes. Proper configuration ensures seamless integration of automated API documentation and routing into the project, supporting maintainable and type-safe API development.