tsoa.json

Overview

The `tsoa.json` file is a configuration file used by **tsoa**, a TypeScript framework designed to generate OpenAPI-compliant REST API documentation and route handling automatically. This JSON file defines how tsoa should process the source code and generate the API specification and routes for the application.

In this project, `tsoa.json` configures tsoa to:

• Identify the application's entry point.

• Specify where the controller files reside.

• Define the behavior for handling additional properties in request bodies.

• Set output directories for generated API specifications and routes.

• Exclude certain directories from processing.

This file acts as the central configuration that guides tsoa's code analysis and code generation tasks, making it crucial for maintaining the API contract and routing structure.

Detailed Explanation of Configuration Properties

Root Properties

spec Object

routes Object

Usage and Workflow

1. Entry Point Definition
   The entryFile (src/app.ts) is the starting point for tsoa's static analysis. tsoa scans the imports and dependencies starting from this file to build the API model.

2. Controller Discovery
   The controllerPathGlobs pattern (src/**/controller.ts) tells tsoa where to find the controller files. Controllers contain decorated TypeScript classes with methods that define API endpoints.

3. Model Validation Behavior
   The noImplicitAdditionalProperties set to "throw-on-extras" enforces strict validation. If an incoming request body contains any properties that are not explicitly defined in the model, tsoa will generate runtime validation that throws an error, helping maintain API contract integrity.

4. Spec and Routes Generation

   • The OpenAPI specification files are generated into the directory specified by spec.outputDirectory (here, "src"), enabling tools like Swagger UI or Postman to consume the API documentation.

   • The route handlers needed to connect the API endpoints to the actual controller implementations are generated into routes.routesDir ("src"), integrating with the application server.

5. Ignoring Files
   The ignore array ensures that generated or external code (e.g., node_modules or build output directories like dist) is excluded from tsoa processing, improving performance and avoiding conflicts.

Important Implementation Details

• Strict Validation Mode:
  By setting "noImplicitAdditionalProperties": "throw-on-extras", the API enforces a strict schema validation at runtime. This is crucial for API stability, ensuring clients do not send unexpected fields.

• Globbing Pattern for Controllers:
  The glob pattern src/**/controller.ts allows flexible placement of controllers anywhere under the src directory, as long as the file is named controller.ts. This supports modular project structures.

• Single Source of Truth:
  The entryFile acts as the root of the API definition, promoting a single point for tsoa to analyze the whole API, which reduces inconsistencies.

Interaction with Other Parts of the Project

• Source Code (src/app.ts and Controllers):
  tsoa reads the TypeScript source code starting from src/app.ts and the controllers matched by the glob to generate both OpenAPI specs and routes. Thus, this config file tightly couples tsoa’s generation process with the project’s source structure.

• Generated API Specification (OpenAPI):
  The specification output in src can be used by API documentation tools or client SDK generators, facilitating API consumption and integration.

• Routing Files:
  Generated routes are saved to src, typically imported by the main application server to wire REST endpoints to controller logic, enabling automatic route registration.

• Build and Deployment:
  Ignored folders like node_modules and dist are excluded from the tsoa workflow, ensuring that only source files are analyzed and generated artifacts are clean.

Example Usage

To generate OpenAPI specs and routes with this configuration, run:

tsoa spec
tsoa routes

These commands use the `tsoa.json` configuration to:

• Generate openapi.json (or similar) in the src directory.

• Generate route files in src to be included in the app bootstrap.

Visual Diagram

This is a **flowchart** showing how `tsoa.json` configures the generation workflow and relates to project components:

flowchart TD
    A[tsoa.json Configuration] --> B[Entry Point: src/app.ts]
    A --> C[Controller Files: src/**/controller.ts]
    A --> D[No Implicit Additional Properties: throw-on-extras]
    A --> E[Ignore Patterns: node_modules, dist]
    B --> F[tsoa Static Analysis]
    C --> F
    E -. Excluded from -.-> F
    F --> G[Generate OpenAPI Spec in src/]
    F --> H[Generate Routes in src/]
    G --> I[API Documentation / Client SDKs]
    H --> J[Application Route Registration]

Summary

• tsoa.json is a critical configuration file for tsoa to generate API specs and route files.

• It defines entry points, controller locations, validation rules, output directories, and ignore patterns.

• Ensures strict runtime validation with "throw-on-extras".

• Drives automated OpenAPI spec and route generation, enabling consistent API documentation and routing.

• Integrates tightly with the project source structure, facilitating modular and scalable API development.

This file is essential for maintaining the API contract and automating REST endpoint wiring in the application.