tsoa.json

Overview

The `tsoa.json` file serves as the primary configuration file for the **tsoa** framework within this project. TSOA is a TypeScript framework used to automatically generate OpenAPI (Swagger) specifications and route handling based on controller source files. This configuration file guides the tsoa CLI tools to locate the entry point of the application, controller files, output directory for generated specs and routes, and other key settings that influence how the API documentation and routing are generated.

In this project, `tsoa.json` ensures that OpenAPI v3 specifications and routing files are generated accurately reflecting the controllers located under `src/**/controller.ts`, providing strict type safety rules and ignoring build or dependency output folders.

Configuration Properties Explained

Detailed Explanation

1. entryFile

• Purpose:
  Specifies the root file of the project where tsoa begins parsing TypeScript source code for API metadata.

• Usage:
  The file src/app.ts is expected to bootstrap the application, import controllers, and define any global middleware or settings.

• Example:
  If your app entry point was index.ts, you would set "entryFile": "src/index.ts".

2. noImplicitAdditionalProperties

• Purpose:
  Controls how tsoa validates request body objects against defined TypeScript interfaces or classes.
  Options:

  • "throw-on-extras": Throw an error if incoming request bodies contain properties not defined in the model.

  • "silently-remove-extras": Strip out additional properties without error.

  • "ignore": Do not perform any checks on extra properties.

• Effect:
  In this config, "throw-on-extras" enforces strict validation, improving API robustness by rejecting invalid requests.

3. controllerPathGlobs

• Purpose:
  Defines where tsoa looks for controller files, which contain route decorators and method definitions for API endpoints.

• Details:
  The glob pattern src/**/controller.ts means any controller.ts file under src and its subdirectories will be included.

• Example:
  If controllers were split across multiple files, e.g., userController.ts and productController.ts, the pattern would need to be adjusted accordingly.

4. spec

• Purpose:
  Configures how and where the OpenAPI spec is generated.

• Properties:

  • outputDirectory: Where the generated OpenAPI JSON/YAML files will be saved. Here, it is set to the src directory.

  • specVersion: Version of OpenAPI spec to generate. Version 3 is the current standard offering improved features over version 2.

5. routes

• Purpose:
  Specifies where to generate routes that tsoa creates to wire controllers to Express or other supported frameworks.

• Property:

  • routesDir: Directory where generated route files will be stored (src in this case).

6. ignore

• Purpose:
  Lists glob patterns of files or directories that tsoa should skip during scanning or generating routes/specs.

• Details:
  Commonly used to exclude node_modules and build output directories like dist.

Usage Example

Given this configuration, a typical workflow would be:

1. Write your controllers in files matching pattern src/**/controller.ts.

2. Run the tsoa CLI commands (e.g., tsoa spec and tsoa routes) which will:

   • Parse src/app.ts as the entry point.

   • Scan all matching controller files.

   • Generate OpenAPI v3 spec files in src/.

   • Generate route files in src/.

3. Use the generated routes in your Express app to wire up the API endpoints.

4. Use the OpenAPI spec to power documentation, client generation, or validation.

Interaction with Other Parts of the Application

• Controllers:
  This config tells tsoa where to find controllers, so any changes in controller structure or location require updates here.

• Entry File (src/app.ts):
  This file is the root context for tsoa scanning and should import or reference controllers and setup the app.

• Build/Output Folders:
  The ignore patterns prevent tsoa from scanning unnecessary files, improving performance and avoiding conflicts.

• Generated Files:
  The spec and routes files created by tsoa are later imported into the application or documentation tools.

Important Implementation Details

• The "throw-on-extras" setting enforces strict validation, which can cause requests with unexpected properties to be rejected upfront.

• Glob patterns use double star ** for recursive matching.

• Spec version 3 enables use of the latest OpenAPI features such as callbacks, improved parameter definitions, and links.

Diagram: Configuration Structure and Workflow

flowchart TD
    A[tsoa.json Configuration]
    A --> B[Entry File: src/app.ts]
    A --> C[Controller Files: src/**/controller.ts]
    A --> D[Spec Generation]
    A --> E[Route Generation]
    A --> F[Ignore Patterns]

    B -->|Provides context and types| C
    C -->|Scanned by tsoa| D
    C -->|Scanned by tsoa| E

    D -->|Outputs OpenAPI v3 spec files| G[Directory: src/]
    E -->|Outputs routes| H[Directory: src/]

    F -.->|Exclude scanning| B
    F -.->|Exclude scanning| C

Summary

The `tsoa.json` file is a central piece in automating the generation of API routes and OpenAPI documentation in this TypeScript project. Its configuration ensures proper file discovery, strict validation settings, and correct output locations, enabling developers to maintain a clean and robust API ecosystem with minimal manual overhead. Adjusting this file tailors tsoa's behavior to fit the project’s architecture and development workflow.