tsoa.json

Overview

The `tsoa.json` file is a configuration file used by **tsoa**, a TypeScript OpenAPI and routing generation tool. This file defines how tsoa should scan, generate, and output API routes and specifications for the project. It plays a crucial role in automating the creation of OpenAPI-compliant API documentation and route handlers based on TypeScript controller files.

This configuration enables seamless integration between the TypeScript codebase and the OpenAPI ecosystem, facilitating automatic validation, routing, and documentation generation with minimal manual setup.

Configuration Properties

1. entryFile: string

• Description:
  Specifies the main entry TypeScript file of the application. tsoa uses this file as the starting point to trace and analyze the application's API controllers and types.

• Value in this file: "src/app.ts"

• Example usage:
  If your main app file is src/server.ts, you would set "entryFile": "src/server.ts".

2. noImplicitAdditionalProperties: string

• Description:
  Controls how tsoa handles properties not explicitly defined in your TypeScript interfaces or classes when generating and validating OpenAPI schemas.

• Possible values:

  • "ignore": Additional properties are allowed without error.

  • "silently-remove-extras": Additional properties are removed silently during validation.

  • "throw-on-extras": Throws an error if additional properties are present (strict mode).

• Value in this file: "throw-on-extras"
  This means the API will reject requests containing unexpected properties, enforcing strict schema adherence.

3. controllerPathGlobs: string[]

• Description:
  An array of glob patterns that specify where tsoa should look for controller files. Controllers define the API endpoints and their behaviors.

• Value in this file:

  ["src/**/controller.ts"]
  

  This pattern matches any controller.ts file inside any subdirectory of src, enabling modular controller placement.

4. spec: object

• Description:
  Configuration related to the OpenAPI specification generation.

• Properties:

  • outputDirectory: string — Directory where the generated OpenAPI spec files (e.g., openapi.json) will be saved.

  • specVersion: number — The OpenAPI version to target (e.g., 3 for OpenAPI 3.x).

• Value in this file:

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

  The OpenAPI spec files will be generated inside the src folder using OpenAPI version 3.

5. routes: object

• Description:
  Configuration related to route generation.

• Properties:

  • routesDir: string — Directory where tsoa will generate route files (files that map HTTP requests to controller methods).

• Value in this file:

  {
    "routesDir": "src"
  }
  

  Routes will be generated inside the src directory.

6. ignore: string[]

• Description:
  List of glob patterns for files/directories that tsoa should ignore when scanning for controllers or generating routes/specs. Useful to exclude build outputs and dependencies.

• Value in this file:

  ["**/node_modules/**", "**/dist/**"]
  

  Ensures that node modules and distribution builds are not scanned or processed.

How This File Interacts with the System

• During Development:
  When running tsoa CLI commands (e.g., tsoa spec or tsoa routes), this configuration file guides how tsoa scans the codebase, generates the OpenAPI spec, and creates route files. It ensures that the API documentation and routing code remain synchronized with the TypeScript controllers.

• With Controllers:
  The controllerPathGlobs points to all controller files that define API endpoints. tsoa reads decorators and types from these files to build the API contract.

• With the Application:
  The generated routes and OpenAPI spec are integrated into the server application, typically imported in the main app file (e.g., src/app.ts) to enable request routing and API documentation endpoints.

• In CI/CD Pipelines:
  This file is crucial for automated generation of API docs and route handlers during build processes, ensuring the deployed API is consistent with the source code.

Usage Example

Suppose you have a controller at `src/user/controller.ts`:

import { Controller, Get, Route } from 'tsoa';

@Route('users')
export class UserController extends Controller {
  @Get()
  public async getUsers(): Promise<string[]> {
    return ['Alice', 'Bob'];
  }
}

• Running tsoa spec will generate an OpenAPI spec in src/openapi.json describing the /users GET endpoint.

• Running tsoa routes will generate route files in src/ that map HTTP requests to UserController.

Implementation Details

• The file is a plain JSON configuration file, not code.

• It follows the tsoa configuration schema, which tsoa CLI tools use.

• The "throw-on-extras" setting enforces strict API schema validation, preventing clients from sending unexpected data.

• Glob patterns in controllerPathGlobs and ignore use standard minimatch syntax.

• The output directories (spec.outputDirectory and routes.routesDir) are designed to keep generated files close to source for easy access and version control.

Visual Diagram

The following flowchart illustrates how `tsoa.json` configures the workflow of tsoa in the system:

flowchart TD
    A[tsoa.json Configuration] --> B[Scan entryFile: src/app.ts]
    B --> C[Find controllers using controllerPathGlobs]
    C --> D[Parse controller decorators & types]
    D --> E[Generate OpenAPI Spec in src/]
    D --> F[Generate Route Handlers in src/]
    E --> G[OpenAPI Docs & Validation]
    F --> H[API Route Integration in Application]
    I[ignore patterns] -.-> B

Summary

The `tsoa.json` file is a central configuration for integrating tsoa into a TypeScript project. It defines how tsoa identifies API controllers, generates OpenAPI specifications, and creates routing files. This file ensures strong typing, validation, and up-to-date API documentation, streamlining API development and maintenance in the project.