tsoa.json

Overview

`tsoa.json` is a configuration file used by the **tsoa** framework, which automates the generation of OpenAPI-compliant REST API specifications and routes from TypeScript source code. This file defines key settings that control how tsoa scans the project files, generates API specs, creates routing files, and handles validation.

By specifying paths, output directories, and validation policies, `tsoa.json` enables seamless integration of tsoa into a TypeScript backend project. It acts as the central configuration point that guides tsoa in extracting API metadata from annotated controller files and producing corresponding artifacts needed for API documentation and routing.

Configuration Details

The file is a JSON object with the following top-level properties:

Property: entryFile

• Type: string

• Purpose: Specifies the path to the main TypeScript entry file of your backend project (relative to the root).

• Example: "src/app.ts"

• Usage: tsoa uses this file as the root for performing type analysis and resolving imports.

Property: noImplicitAdditionalProperties

• Type: "throw-on-extras" (string)

• Purpose: Controls validation behavior when the request body contains extra properties not defined in the model.

• Possible values:

  • "ignore": Ignore additional properties.

  • "silently-remove-extras": Remove additional properties silently.

  • "throw-on-extras": Throw an error if extra properties are present.

• Current Value: "throw-on-extras"

• Effect: Enforces strict validation to ensure clients send only defined fields.

Property: controllerPathGlobs

• Type: string[]

• Purpose: Defines glob patterns used to locate controller files with tsoa decorators (@Route, @Get, @Post, etc.).

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

• Effect: tsoa scans all matching files to generate API specs and routing metadata.

Property: spec

• Type: object

• Properties:

  • outputDirectory: string - Directory where the OpenAPI spec file(s) will be generated.

  • specVersion: number - The OpenAPI version to target (3 means OpenAPI 3.x).

• Example:

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

• Usage: Controls where tsoa outputs the generated openapi.json or swagger.json file and which OpenAPI version format to use.

Property: routes

• Type: object

• Properties:

  • routesDir: string - Directory where tsoa will generate routing files (e.g., routes.ts).

• Example:

  "routes": {
    "routesDir": "src"
  }
  

• Usage: Specifies the location for generated route handler files that wire controllers to Express or other frameworks.

Property: ignore

• Type: string[]

• Purpose: Glob patterns to exclude certain files or folders from tsoa processing.

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

• Effect: Prevents scanning of dependencies, build output, or other irrelevant files.

How This File Interacts with the System

• tsoa CLI and Build Tools: When you run tsoa commands like tsoa spec or tsoa routes, the tool reads tsoa.json to understand which files to scan and where to output generated artifacts.

• Source Code Controllers: The controllerPathGlobs guide tsoa to find controller files decorated with tsoa annotations to extract API metadata.

• OpenAPI Spec Generation: The spec property controls where and how the OpenAPI spec is generated, which is used for API documentation or client generation.

• Route Generation: The routes property guides where tsoa outputs generated routing files that integrate controllers with the web server framework.

• Validation Enforcement: The noImplicitAdditionalProperties setting affects runtime request validation by generated middleware.

• Ignored Folders: The ignore list keeps tsoa from processing irrelevant files, improving performance and avoiding conflicts.

Usage Example in a Project Workflow

1. Define Controllers:
   Create TypeScript files matching src/**/controller.ts with tsoa decorators, e.g.,

   import { Controller, Get, Route } from 'tsoa';
   
   @Route('users')
   export class UsersController extends Controller {
     @Get()
     public async getUsers() {
       return [{ id: 1, name: 'Alice' }];
     }
   }
   

2. Configure tsoa.json:
   Ensure tsoa.json is set with correct paths and settings (as in this file).

3. Generate API Spec and Routes:
   Run:

   tsoa spec
   tsoa routes
   

   This generates:

   • OpenAPI spec file in src/

   • Routes file in src/

4. Integrate Generated Routes:
   Import and use the routes in your main application file (src/app.ts).

Important Implementation Details

• Strict Validation: "throw-on-extras" enforces strict compliance to declared model schemas, helping catch client errors early.

• Glob Patterns: The use of globs allows flexible file organization without hardcoding paths.

• OpenAPI 3: Targeting OpenAPI spec version 3 ensures compatibility with modern API tools and documentation generators.

• Separation of Concerns: By generating routes and specs separately, tsoa promotes clean separation between API definition and runtime integration.

Mermaid Diagram: Configuration Structure Flow

The following flowchart illustrates how the main configuration properties relate and drive the tsoa processing 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]
    A --> F[routes]
    A --> G[ignore]

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

    F --> F1[routesDir: src]

    subgraph Processing Workflow
        C --> H[Scan Controllers]
        H --> I[Extract API Metadata]
        I --> J[Generate OpenAPI Spec]
        J --> E1
        I --> K[Generate Routes]
        K --> F1
        D --> L[Validate Requests Strictly]
    end

    G -.->|Exclude files| H

Summary

`tsoa.json` is a critical configuration file in a tsoa-enabled TypeScript backend project. It defines:

• The main entry point for type analysis (entryFile).

• Where to find controller files (controllerPathGlobs).

• Validation rules for request bodies (noImplicitAdditionalProperties).

• Output directories for API specification and routing (spec, routes).

• Files or folders to ignore during processing (ignore).

This configuration enables automated generation of OpenAPI specs and routing files, enforcing strict API validation and ensuring seamless integration between TypeScript code and API documentation/services.