tsoa.json

Overview

The `tsoa.json` file is a configuration file used by the **tsoa** framework, a TypeScript tool that facilitates building RESTful APIs with automatic OpenAPI (Swagger) specification generation and route generation. This file defines how tsoa should process the source code, generate API documentation, and create routing files.

In this project, `tsoa.json` configures the entry point of the application, routing options, specification generation settings, and file patterns to include or exclude in the tsoa processing pipeline.

Detailed Explanation

Configuration Structure

The file is a JSON object consisting of several key properties that control tsoa's behavior:

Properties Breakdown

entryFile

• Type: string

• Example: "src/app.ts"

• Description: Specifies the main entry point of the application. tsoa uses this file to start scanning for decorators and controllers.

noImplicitAdditionalProperties

• Type: "throw-on-extras" | "silently-remove-extras" | "ignore"

• Example: "throw-on-extras"

• Description: Controls validation behavior for additional properties on models not explicitly defined.

  • "throw-on-extras": Validation will fail if unexpected properties are present.

  • "silently-remove-extras": Extra properties will be removed silently.

  • "ignore": No validation on extra properties.

controllerPathGlobs

• Type: string[]

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

• Description: Specifies glob pattern(s) to locate controller files that contain the REST API routes.

spec

• Type: object

• Description: Contains settings specific to OpenAPI spec generation.

  • outputDirectory: Where the generated OpenAPI JSON/YAML files will be stored.

  • specVersion: Indicates the OpenAPI version to generate (3 for OpenAPI 3.0).

routes

• Type: object

• Description: Contains settings for route file generation.

  • routesDir: Directory for the generated route handler files.

ignore

• Type: string[]

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

• Description: Glob patterns for files or directories to exclude from scanning and processing by tsoa.

Usage Example

Suppose you have a TypeScript REST API project structured as follows:

src/
 ├─ app.ts              # Main app entry point
 ├─ userController.ts   # Controller file
 └─ ...

With the given `tsoa.json`:

• tsoa starts scanning from src/app.ts.

• It looks for controllers matching src/**/controller.ts (e.g., userController.ts).

• It generates OpenAPI 3.0 spec files in the src directory.

• It outputs route files into the src directory.

• It ignores scanning any files under node_modules and dist folders.

• It enforces strict model validation by throwing errors on extra properties.

After running tsoa commands (e.g., `tsoa spec` or `tsoa routes`), the generated OpenAPI JSON/YAML and route files will appear in the specified directories.

Implementation Details and Algorithms

`tsoa.json` itself does not contain executable code or algorithms but instructs the tsoa CLI and build tools how to:

• Traverse source files starting at the entryFile.

• Identify controller classes and their decorated methods using the controllerPathGlobs.

• Analyze TypeScript types and decorators to generate OpenAPI-compliant specification files.

• Automatically generate route files that wire the HTTP endpoints to controller methods.

• Enforce validation rules based on noImplicitAdditionalProperties.

• Exclude unnecessary files from processing for performance and correctness.

This configuration enables seamless integration between source code and API documentation and routing, reducing manual boilerplate.

Interaction with Other Parts of the System

• Source code: tsoa scans TypeScript files (controllers and models) referenced indirectly via entryFile and controllerPathGlobs.

• Build process: tsoa commands use this config to generate OpenAPI specs and route files that are then compiled and bundled with the application.

• API documentation: The generated OpenAPI spec files are used to serve API docs via Swagger UI or other tools.

• Routing layer: Generated route files provide express-style middleware that connect HTTP routes to controller methods.

• Validation: The noImplicitAdditionalProperties option influences runtime request validation behavior by controlling schema strictness.

Overall, this file acts as the central configuration point for the tsoa toolchain, ensuring consistency between source code, API documentation, and routing logic.

Mermaid Diagram: Configuration Structure Flowchart

flowchart TD
    A[tsoa.json Configuration] --> B[Entry File: src/app.ts]
    A --> C[Controller Globs: src/**/controller.ts]
    A --> D[No Implicit Additional Properties: throw-on-extras]
    A --> E[Spec Generation]
    E --> E1[Output Directory: src]
    E --> E2[Spec Version: 3]
    A --> F[Routes Generation]
    F --> F1[Routes Directory: src]
    A --> G[Ignore Patterns]
    G --> G1["**/node_modules/**"]
    G --> G2["**/dist/**"]

Summary

The `tsoa.json` configuration file is essential for integrating tsoa into a TypeScript REST API project. It defines where tsoa looks for API controllers, how it generates OpenAPI specifications and route files, and how strict the validation on model properties should be. By properly configuring this file, developers automate API documentation and routing generation, improving maintainability and reducing manual coding errors.