tsoa.json

Overview

`tsoa.json` is a configuration file used by the **tsoa** framework, a TypeScript tool for generating OpenAPI specifications and routing controllers automatically. This JSON file defines key settings that control how tsoa scans the source code, generates API documentation, and creates routing files within the project.

The file’s primary purpose is to configure tsoa's behavior including:

• Entry point of the application

• Controller file locations

• OpenAPI specification generation details

• Route generation settings

• File and directory patterns to ignore during processing

• Rules for handling additional properties in request bodies

This configuration enables seamless integration of tsoa into the build and documentation workflow, ensuring consistent API spec generation and routing setup.

Configuration Properties

entryFile: string

• Description: Specifies the main entry point file of the application. tsoa uses this file as the starting point to analyze the app's controllers and generate routes.

• Example: "src/app.ts"

• Usage: This should point to the file where the application bootstrap or express app is initialized.

noImplicitAdditionalProperties: string

• Description: Determines the behavior when additional properties (not explicitly defined in the model/interface) are encountered in API requests.

• Possible values:

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

  • "silently-remove-extras": Removes extra properties without error.

  • "ignore": Allows additional properties without restrictions.

• Example: "throw-on-extras"

• Usage: Helps enforce strict validation of input data against the defined models.

controllerPathGlobs: string[]

• Description: An array of glob patterns to locate controller files within the project.

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

• Usage: tsoa uses these patterns to find all controller files which define API endpoints.

spec: { outputDirectory: string, specVersion: number }

• Description: Configuration related to OpenAPI specification generation.

  • outputDirectory: Directory where the generated OpenAPI spec files are saved.

  • specVersion: Version of the OpenAPI spec to generate (e.g., 3 for OpenAPI 3.0).

• Example:

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

• Usage: Defines where the API documentation files will be stored and which OpenAPI version they conform to.

routes: { routesDir: string }

• Description: Defines where tsoa should output the generated routing files.

• Example:

  {
    "routesDir": "src"
  }
  

• Usage: Routes generated from controllers will be saved here for integration with the application.

ignore: string[]

• Description: Array of glob patterns for files or directories that tsoa should ignore when scanning for controllers or models.

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

• Usage: Prevents tsoa from processing non-source or build files, speeding up generation and avoiding conflicts.

Usage Example

{
  "entryFile": "src/app.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": ["src/**/controller.ts"],
  "spec": {
    "outputDirectory": "src",
    "specVersion": 3
  },
  "routes": {
    "routesDir": "src"
  },
  "ignore": ["**/node_modules/**", "**/dist/**"]
}

This configuration tells tsoa to:

• Start scanning from src/app.ts

• Enforce strict validation with no extra properties allowed in API requests

• Find controllers matching src/**/controller.ts

• Generate OpenAPI 3 specification files in the src folder

• Generate routing files in the src folder

• Ignore node_modules and dist directories during scanning

Implementation Details

• This file uses glob patterns (controllerPathGlobs and ignore) for flexible and recursive file matching.

• The noImplicitAdditionalProperties setting is critical for API input validation, influencing runtime behavior of validation middleware.

• The separation of spec and routes output directories allows finer control over generated outputs, useful in monorepos or complex builds.

• tsoa reads this JSON file during its CLI invocation or programmatic usage to determine how to process the TypeScript codebase.

Interaction with Other Parts of the System

• Controllers: The locations defined by controllerPathGlobs point to files where tsoa expects to find decorated controller classes that define API endpoints.

• App entry file (entryFile): The starting point for tsoa to bootstrap analysis, usually where the Express or Koa app is initialized.

• OpenAPI spec generation: The spec settings dictate where the generated OpenAPI JSON/YAML files are saved, which are later used for API documentation or client generation.

• Route generation: The routes settings specify where to output generated route files that wire controllers to the framework's routing system.

• Ignore patterns: This prevents unnecessary files from being processed, improving performance and avoiding potential errors.

• Build and CI pipelines: This file is often referenced in scripts that generate API docs or routes as part of build or deployment processes.

Visual Diagram

Below is a flowchart illustrating the main configuration properties and their relationships in the `tsoa.json` file and how tsoa uses them.

flowchart TD
    subgraph tsoa.json Configuration
        EF[entryFile: "src/app.ts"]
        NI[noImplicitAdditionalProperties: "throw-on-extras"]
        CPG[controllerPathGlobs: ["src/**/controller.ts"]]
        IGN[ignore: ["**/node_modules/**", "**/dist/**"]]
        SPEC[spec]
        ROUTES[routes]
    end

    SPEC -->|outputDirectory: "src"| SPEC_OUT[Spec Output Directory]
    SPEC -->|specVersion: 3| SPEC_VER[Spec Version]

    ROUTES -->|routesDir: "src"| ROUTES_OUT[Routes Output Directory]

    EF -->|Start scanning| CONTROLLERS[Controller Files Found]
    CPG --> CONTROLLERS
    IGN -.->|Exclude| CONTROLLERS

    CONTROLLERS -->|Generate| ROUTES_OUT
    CONTROLLERS -->|Generate| SPEC_OUT

    NI -->|Validation Rules| CONTROLLERS

Summary

`tsoa.json` is a concise yet powerful configuration file that governs how the tsoa framework scans your TypeScript project, validates API inputs, generates OpenAPI specs, and outputs route files. Proper configuration ensures automatic and consistent API documentation and routing, greatly simplifying backend development and maintenance.

**End of Documentation**