tsoa.json

Overview

The `tsoa.json` file is a configuration file used by the **tsoa** framework, which is a TypeScript OpenAPI and Swagger generation tool. This configuration file defines how tsoa will generate API documentation and routes based on the project's source code.

Specifically, it guides tsoa in locating the entry point of the application, where to find controller files, how to handle additional properties in models, where to output generated OpenAPI specification files and routes, and which files or directories to ignore during processing.

This file plays a pivotal role in automating the generation of API specs and routes, ensuring that the API documentation stays consistent with the codebase and reducing manual overhead.

Configuration Properties Explained

Below is a detailed explanation of each property in the `tsoa.json` file, including its purpose, accepted values, and usage.

1. entryFile

• Type: string

• Description: Specifies the main entry file of the application from which tsoa will start analyzing the project. This file typically bootstraps the Express or other server framework and imports controllers.

• Example: "src/app.ts"

• Usage: tsoa uses this file as the starting point to resolve and analyze all TypeScript files and dependencies related to API controllers.

2. noImplicitAdditionalProperties

• Type: string (enum: "throw-on-extras" | "silently-remove-extras" | "ignore")

• Description: Defines how tsoa handles additional properties not explicitly defined in your models when generating validation schemas and runtime checks.

• Values:

  • "throw-on-extras": Throws an error if extra properties are present in the incoming data.

  • "silently-remove-extras": Ignores extra properties by removing them silently.

  • "ignore": Allows extra properties without any validation or removal.

• Example: "throw-on-extras"

• Usage: This setting improves model validation strictness and prevents unexpected data from passing through API endpoints.

3. controllerPathGlobs

• Type: string[]

• Description: An array of glob patterns that tell tsoa where to find the controller files. Controllers define the API endpoints.

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

• Usage: tsoa scans these files to extract routing and OpenAPI metadata.

4. spec

• Type: object

• Description: Defines how and where to generate the OpenAPI specification.

• Properties:

  • outputDirectory: The directory where the generated OpenAPI spec files will be saved.

  • specVersion: The OpenAPI version to use for the generated spec (usually 3).

• Example:

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

• Usage: Enables tsoa to output up-to-date OpenAPI JSON or YAML describing your API in the specified folder.

5. routes

• Type: object

• Description: Defines where to generate the routing files used by the application to handle API requests.

• Properties:

  • routesDir: Directory where tsoa will place the generated route handlers.

• Example:

  {
    "routesDir": "src"
  }
  

• Usage: This allows integration of generated route files into the project build.

6. ignore

• Type: string[]

• Description: Glob patterns specifying files or directories that tsoa should ignore during scanning.

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

• Usage: Prevents tsoa from processing dependencies or build output directories.

Usage Example

Assuming you have a TypeScript project with controllers under the `src` directory, your `tsoa.json` configuration as shown will:

• Start from src/app.ts as the entry point.

• Look for all controller files matching src/**/controller.ts.

• Throw errors if extra properties are found in your models.

• Generate OpenAPI 3.0 specification files inside the src folder.

• Generate route files also inside the src folder.

• Ignore scanning files inside node_modules and dist.

You can then run tsoa CLI commands like:

tsoa spec
tsoa routes

to generate updated API specs and routes accordingly.

Implementation Details

• Glob Patterns: Uses glob syntax to flexibly find files across nested directories.

• Validation Strategy: The noImplicitAdditionalProperties setting enforces strict data validation consistency.

• Output Management: Separates concerns by generating specs and routes into configurable directories.

• Integration: Designed to seamlessly integrate into TypeScript projects with minimal manual setup.

Interaction with Other Parts of the System

• Entry File (src/app.ts): Acts as the bootstrap point; tsoa analyzes this file to discover all API controllers.

• Controllers (src/**/controller.ts): This glob pattern ensures all controller files defining API endpoints are included in the generation process.

• Generated Routes: The routes generated in src are imported or used by the application server to route requests correctly.

• OpenAPI Specs: The specs generated can be consumed by API documentation tools (like Swagger UI) or used for client SDK generation.

• Ignored Folders: Ensures build artifacts and dependencies do not pollute generation or cause errors.

Mermaid Diagram: Configuration Structure

flowchart TD
    A[tsoa.json Configuration]
    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]
    G --> G1[**/node_modules/**]
    G --> G2[**/dist/**]

Summary

The `tsoa.json` file is a critical configuration artifact in a tsoa-based TypeScript project that orchestrates how API documentation and routing are generated. By specifying entry points, controller locations, output directories, and validation behaviors, it streamlines the synchronization between your source code and API documentation, enabling robust and maintainable API development workflows.