tsoa.json

Overview

The `tsoa.json` file is a configuration file for [tsoa](https://github.com/lukeautry/tsoa), a TypeScript framework used to generate OpenAPI-compliant REST API documentation and route definitions automatically from TypeScript source code. This JSON file defines key configuration parameters that instruct tsoa how to locate application source files, generate API specification files (OpenAPI/Swagger), and create routing files.

By configuring `tsoa.json`, developers streamline the generation of API documentation and routes, ensuring consistency between TypeScript code and API contracts, reducing manual documentation effort, and improving maintainability.

Configuration Properties Explanation

The file consists of a JSON object with the following main properties:

Detailed Property Descriptions

entryFile: string

• Purpose: Specifies the main TypeScript file that serves as the application's entry point. tsoa uses this file as the starting point to analyze your app's types and controllers.

• Example: "src/app.ts"

noImplicitAdditionalProperties: "throw-on-extras"

• Purpose: Enforces strict JSON request body validation by throwing errors when extra properties (not defined in the model) are included.

• Values:

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

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

  • "ignore": Allows extra properties without any validation.

• Usage: Helps maintain strict API contracts and data integrity.

controllerPathGlobs: string[]

• Purpose: Defines paths (using glob patterns) to locate controller files. Controllers contain methods decorated with tsoa decorators to define API endpoints.

• Example: ["src/**/controller.ts"] means any controller.ts file inside any subdirectory of src.

spec: object

• Properties:

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

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

• Example:

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

routes: object

• Properties:

  • routesDir: string: Directory path where tsoa will output the generated route files.

• Example:

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

ignore: string[]

• Purpose: Specifies files or directories to exclude from tsoa processing. Helps avoid parsing dependencies or build artifacts.

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

Usage Example

Given this configuration, running tsoa CLI commands such as `tsoa spec` and `tsoa routes` will:

• Parse the src/app.ts entry file.

• Recursively locate all controller files matching src/**/controller.ts.

• Validate request models strictly by throwing errors when unknown properties are present.

• Generate OpenAPI spec files under the src directory.

• Generate route files under the src directory.

• Ignore files inside node_modules and dist folders during parsing.

This setup ensures that API documentation and routing remain synchronized with the TypeScript source code.

Implementation Details

• Parsing Approach: tsoa performs static analysis on the TypeScript entry file and all referenced controller files to extract metadata from decorators such as @Route, @Get, @Post, etc.

• Validation Mode: Setting "throw-on-extras" enforces strict validation, ensuring the API does not accept unexpected properties, which is crucial for security and data integrity.

• Glob Patterns: The controller path uses glob patterns allowing flexible file organization.

• Spec Generation: The OpenAPI 3 specification generated can be used by tools like Swagger UI or Postman to visualize and test the API.

• Routes Generation: tsoa generates routing code that wires Express (or other supported frameworks) with the controllers, reducing boilerplate code.

Interaction with Other System Components

• With Source Code: It reads and analyzes TypeScript source files (controllers and models) annotated with tsoa decorators.

• With Build Process: The generated spec and routes files are usually part of the build artifacts and deployed alongside the application.

• With API Clients: The OpenAPI spec generated from this config is consumed by frontend applications, API gateways, or automated testing tools.

• With Validation Middleware: The "throw-on-extras" setting directly influences runtime validation behavior during API request handling.

Mermaid Diagram

This file is a configuration file defining properties for tsoa CLI behavior. A flowchart showing the main configuration properties and their relationships to the tsoa workflow is appropriate.

flowchart TD
    A[tsoa.json] --> B[entryFile: src/app.ts]
    A --> C[noImplicitAdditionalProperties: throw-on-extras]
    A --> D[controllerPathGlobs: src/**/controller.ts]
    A --> E[spec]
    A --> F[routes]
    A --> G[ignore]

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

    F --> F1[routesDir: src]

    B --> H[Parse entry file]
    D --> I[Find controllers]
    H --> J[Analyze source code]
    I --> J
    J --> K[Generate OpenAPI spec in src/]
    J --> L[Generate routes in src/]

    C --> M[Validate request bodies strictly]
    G --> N[Exclude node_modules and dist]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style J fill:#bbf,stroke:#333,stroke-width:1px

Summary

• tsoa.json configures tsoa to generate API documentation and routing code.

• It specifies entry points, controller file locations, validation policies, and output directories.

• Enables strict validation on request bodies to prevent unexpected data.

• Integrates tightly with TypeScript source code through glob patterns for controllers.

• Facilitates automated OpenAPI spec and routing generation, improving API consistency and developer productivity.

This file is central to the tsoa-based API documentation and routing automation workflow within the project.