tsoa.json

Overview

The `tsoa.json` file is a configuration file for the **tsoa** framework, a TypeScript OpenAPI (Swagger) tool used to automate the generation of API routes and OpenAPI specification files based on TypeScript decorators in controller files.

This JSON file outlines the key settings and behaviors for the tsoa CLI and runtime tools to:

• Locate the entry point of the application.

• Define how to handle additional properties in API models.

• Specify where controllers are located.

• Configure the output for generated OpenAPI specs.

• Set up routing file generation.

• Define patterns of files and folders to ignore.

In short, `tsoa.json` governs how tsoa interprets your TypeScript source code to generate API routes and OpenAPI documentation, acting as a bridge between your source code and runtime API routing and documentation.

Detailed Explanation of Configuration Properties

Explanation and Usage

entryFile

• Purpose: This points tsoa to the starting point of the application. Typically, this is the main TypeScript file that imports or references all controllers.

• Usage: Required for tsoa to resolve dependencies and decorators properly.

noImplicitAdditionalProperties

• Purpose: Controls strictness of model validation related to additional properties not defined in the model.

• Values:

  • "throw-on-extras": Validation will throw errors on unexpected properties.

  • "silently-remove-extras": Extra properties are stripped silently.

  • "ignore": Extra properties are allowed without errors.

• Usage: Helps enforce API contract strictness.

controllerPathGlobs

• Purpose: Specifies where tsoa should look for controller files that contain decorators like @Route, @Get, @Post, etc.

• Usage: Supports glob patterns for flexible file matching.

spec

• Purpose: Configuration about OpenAPI specification generation.

• Properties:

  • outputDirectory: Where the OpenAPI JSON or YAML files are generated.

  • specVersion: Version of OpenAPI spec (v2 or v3).

• Usage: Helps integrate API documentation with tools like Swagger UI.

routes

• Purpose: Configuration of route files generation.

• Properties:

  • routesDir: Directory where tsoa generates route handler files.

• Usage: Enables automatic route wiring from controllers to Express or other frameworks.

ignore

• Purpose: Exclude files or folders from tsoa scanning and processing.

• Usage: Prevents unnecessary files (node_modules, build artifacts) from interfering.

Implementation Details and Algorithms

• Glob Pattern Matching: The controllerPathGlobs and ignore properties utilize glob patterns to dynamically resolve files. This allows flexible and scalable discovery of controller files, which is crucial for large projects.

• Validation Strictness: The noImplicitAdditionalProperties setting impacts runtime model validation. This enforces schema integrity and impacts generated validation code in route handlers.

• OpenAPI Spec Generation: The spec object directs tsoa to parse controller metadata, generate the OpenAPI 3.0 specification, and output it to the defined directory, enabling automated API documentation workflows.

• Route Generation: The routes section configures the output location for route files that tsoa generates, allowing seamless integration with Express or other Node.js web frameworks.

Interaction with Other Parts of the System

• Source Controllers: This file instructs tsoa on where to find controller files (src/**/controller.ts) that contain route definitions and API metadata.

• Entry Point (entryFile): tsoa uses the specified entry file (src/app.ts) to bootstrap the analysis and to resolve dependencies and decorators during compilation.

• Generated Files:

  • Routes: tsoa will generate route files in the src folder as configured, which will be imported into the application for routing.

  • OpenAPI Specs: The OpenAPI documentation files are generated in the src directory, usable by Swagger UI or other tools.

• Build and Deployment: The ignore patterns ensure that build artifacts and dependencies (node_modules, dist) are excluded from tsoa processing, preventing performance issues and incorrect analysis.

In summary, this file is a central configuration hub that connects source code, build processes, API documentation generation, and routing automation in the overall software architecture.

Example Usage

If your project structure looks like:

src/
  app.ts
  userController.ts
  productController.ts
node_modules/
dist/

• entryFile points to src/app.ts.

• Controllers are found matching src/**/controller.ts (e.g., userController.ts, productController.ts).

• API routes and specs get generated inside src/.

• node_modules and dist folders are ignored.

Run tsoa CLI commands such as:

tsoa routes
tsoa spec

These commands use this configuration to generate the routing and OpenAPI files accordingly.

Mermaid Diagram

Below is a flowchart representing the main configuration properties in `tsoa.json` and how they influence tsoa's workflow:

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

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

    F --> F1[routesDir: src]

    B --> H[tsoa CLI]
    C --> H
    D --> H
    E --> H
    F --> H
    G --> H

    H --> I[Scan source files]
    I --> J[Parse controllers]
    J --> K[Generate routes files in routesDir]
    J --> L[Generate OpenAPI spec in outputDirectory]
    L --> M[Swagger UI / API Docs]
    K --> N[Application routing setup]

    style A fill:#f9f,stroke:#333,stroke-width:1px
    style H fill:#bbf,stroke:#333,stroke-width:1px
    style I,J,K,L,M,N fill:#bfb,stroke:#333,stroke-width:1px

Summary

The `tsoa.json` file is critical for configuring the tsoa framework to automate API routing and OpenAPI spec generation by:

• Specifying the app entry point.

• Defining controller file locations.

• Controlling validation strictness.

• Configuring output directories for generated routes and specs.

• Ignoring unwanted files.

It acts as the central point that connects your TypeScript source code to runtime API routing and documentation generation, streamlining API development and maintenance in TypeScript projects.