tsoa.json

Overview

`tsoa.json` is a configuration file used by the **tsoa** framework, a TypeScript tool for building OpenAPI-compliant REST APIs. This file defines how tsoa generates API routes and OpenAPI specification files based on the TypeScript source code of the project. It specifies key parameters such as the main entry file, controller file paths, output directories, and rules for handling additional properties and ignored paths.

This configuration allows for automated creation and maintenance of API documentation and route files, ensuring consistency between the API implementation and its specification.

Detailed Explanation of Configuration Properties

The file is a JSON object containing several top-level properties. Each property configures a specific aspect of the tsoa tool:

entryFile

• Type: string

• Description: Specifies the main TypeScript file from which tsoa starts analyzing the project to build the API. This file typically contains the initial app setup, such as the Express app instance.

• Example:

  "entryFile": "src/app.ts"
  

• Usage: tsoa will parse this file to find and resolve controllers and routes.

noImplicitAdditionalProperties

• Type: string

• Allowed values: "throw-on-extras", "silently-remove-extras", "ignore"

• Description: Controls how tsoa handles additional properties that are not explicitly defined in models or DTOs.

  • "throw-on-extras": Throws an error if additional properties are found in requests.

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

  • "ignore": Allows additional properties without any action.

• Example:

  "noImplicitAdditionalProperties": "throw-on-extras"
  

• Usage: Helps enforce strict validation on request bodies, improving API robustness.

controllerPathGlobs

• Type: string[] (array of glob patterns)

• Description: Specifies the glob patterns to locate controller files within the project. Controllers define API endpoints and their logic.

• Example:

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

• Usage: tsoa scans these paths to find controller classes decorated with tsoa annotations to generate routes and specification.

spec

• Type: object

• Description: Configures how the OpenAPI specification is generated.

• Properties:

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

  • specVersion (number): The version of the OpenAPI specification to generate (usually 3).

• Example:

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

• Usage: Controls where and how the API documentation is outputted.

routes

• Type: object

• Description: Configures the generation of route files that map HTTP requests to controller methods.

• Properties:

  • routesDir (string): Directory where generated route files will be saved.

• Example:

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

• Usage: Ensures generated route files integrate properly into the application structure.

ignore

• Type: string[] (array of glob patterns)

• Description: Specifies file patterns that tsoa should ignore during scanning for controllers and models.

• Example:

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

• Usage: Prevents unnecessary files or external dependencies from being processed, improving performance and avoiding errors.

Important Implementation Details and Algorithms

• File Parsing and Code Analysis: tsoa uses the entryFile as the root to parse the TypeScript AST (Abstract Syntax Tree). It recursively follows imports and scans files matching the controllerPathGlobs pattern to extract controller classes and their decorated methods.

• Validation Strategy: The noImplicitAdditionalProperties setting configures runtime validation of incoming request payloads by checking for unexpected properties, which helps avoid silent bugs due to unexpected input.

• Code Generation: Based on the discovered controllers and models, tsoa generates:

  • Route files that bind HTTP methods and paths to controller methods.

  • OpenAPI specification files that document the API structure, endpoints, request/response schemas, and security.

• Ignore Patterns: By ignoring paths like node_modules and dist, tsoa avoids scanning compiled or external code, improving efficiency and correctness.

Interaction with Other Parts of the System

• Source Files: The entryFile and controllerPathGlobs point directly to the source TypeScript files that define the API logic.

• Generated Files: The spec.outputDirectory and routes.routesDir specify where tsoa outputs generated files:

  • OpenAPI specification files (e.g., openapi.json) are used by API documentation tools and clients.

  • Route files are imported by the main app to register routes automatically.

• Build Process: This configuration is typically used during the build or development workflow to keep routes and docs in sync with the code.

• Validation Middleware: The noImplicitAdditionalProperties setting influences the generated validation middleware to enforce request body schemas.

Usage Example

Assuming the project has this `tsoa.json`, running tsoa commands like:

tsoa spec
tsoa routes

will:

• Generate an OpenAPI 3 specification file in the src directory.

• Generate route files under src based on controllers found in any controller.ts files under src.

• Enforce strict validation on request bodies, throwing errors if extra properties are detected.

• Ignore scanning node_modules and dist folders.

Mermaid Diagram: Configuration Structure Flow

flowchart TD
    A[tsoa.json Configuration]
    A --> B[entryFile: src/app.ts]
    A --> C[noImplicitAdditionalProperties: throw-on-extras]
    A --> D[controllerPathGlobs: src/**/controller.ts]
    A --> E[spec]
    E --> E1[outputDirectory: src]
    E --> E2[specVersion: 3]
    A --> F[routes]
    F --> F1[routesDir: src]
    A --> G[ignore]
    G --> G1["**/node_modules/**"]
    G --> G2["**/dist/**"]

Summary

`tsoa.json` is a pivotal configuration file for the tsoa framework, enabling automatic generation of API routes and OpenAPI specifications from TypeScript source code. It ensures that the API definitions remain consistent, well-documented, and validated according to strict schemas, improving maintainability and developer experience in building TypeScript-based REST APIs.