tsoa.json

Overview

The `tsoa.json` file is a configuration file used by the **tsoa** framework, a TypeScript tool that facilitates the automatic generation of OpenAPI (Swagger) specifications and routing for RESTful APIs. This JSON file defines how tsoa should scan the project's source code, identify controllers, and generate both API routes and OpenAPI specification files.

In essence, this file controls the behavior of tsoa’s CLI commands, such as `tsoa spec` and `tsoa routes`, by specifying input files, output directories, and other key options to generate API documentation and routing logic that integrates seamlessly with the project’s architecture.

Detailed Explanation of Configuration Fields

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

1. entryFile

• Type: string

• Description:
  Specifies the path to the project's main entry file for tsoa to start type-checking and scanning for decorators. This file acts as the root for tsoa’s static analysis to discover API controllers and models.

• Example:

  "entryFile": "src/app.ts"
  

2. noImplicitAdditionalProperties

• Type: string (enum-like)

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

• Description:
  Controls how tsoa treats additional properties that are not explicitly defined in the API models.

  • "throw-on-extras": validation will fail if extra properties are present.

  • "silently-remove-extras": extra properties are removed from the request objects.

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

• Current setting: "throw-on-extras" — strict validation to ensure only defined properties are accepted.

3. controllerPathGlobs

• Type: string[]

• Description:
  An array of glob patterns that specify where tsoa should look for controller files. Controllers are classes decorated with tsoa decorators like @Route and @Get.

• Example:

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

  This instructs tsoa to scan all files named controller.ts within any subdirectory of src.

4. spec

• Type: object

• Description:
  Configuration options related to the OpenAPI (Swagger) specification generation.

  • outputDirectory: string — directory where the generated OpenAPI spec file(s) will be saved.

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

• Current settings:

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

  This means the OpenAPI spec will be output into the src directory, using OpenAPI version 3.

5. routes

• Type: object

• Description:
  Configuration related to the generation of the routing files that integrate with the web server (e.g., Express).

  • routesDir: string — directory where the generated routes files will be placed.

• Current setting:

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

  Routes will be generated inside the src directory.

6. ignore

• Type: string[]

• Description:
  Glob patterns of files and folders that tsoa should exclude from scanning.

• Current setting:

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

  This prevents scanning of node_modules and dist directories, which are typically not part of the source code.

Usage Example

Assuming the project is set up properly:

• Run tsoa CLI commands such as:

  tsoa spec
  

  to generate the OpenAPI specification file (e.g., openapi.json) inside the src directory.

• Run:

  tsoa routes
  

  to generate route handlers inside the src directory.

The configuration ensures tsoa scans the `src/app.ts` entrypoint, loads all controllers matching `src/**/controller.ts`, ignores `node_modules` and `dist`, and performs strict validation by throwing errors on additional unexpected properties.

Important Implementation Details

• Static Analysis:
  tsoa relies on TypeScript's compiler API to analyze decorators in the codebase starting from the entryFile. This static analysis extracts metadata about routes, parameters, and models.

• Validation Strategy:
  The "throw-on-extras" setting enforces strong API contract adherence, making the API safer by rejecting unexpected input properties. This is critical in production-grade APIs.

• Globbing Patterns:
  Use of glob patterns provides flexibility in project organization but requires careful matching to ensure all controllers are included.

• Separation of Concerns:
  The file cleanly separates concerns between generating API specifications (spec), generating server routes (routes), and input scanning (entryFile and controllerPathGlobs).

Interaction with Other Parts of the System

• Controllers (src//controller.ts):**
  Controllers are source files containing decorated TypeScript classes that define API endpoints. tsoa scans these files as specified by controllerPathGlobs.

• Entry File (src/app.ts):
  Acts as the starting point for tsoa to understand module dependencies and types.

• Generated Files (in src):

  • OpenAPI Spec: Used for API documentation, client generation, or API validation middleware.

  • Routes Files: Typically imported into the server bootstrap code to register API routes with Express or another supported framework.

• Ignore Patterns:
  Prevent unnecessary files from being analyzed, improving performance and preventing errors.

Mermaid Flowchart Diagram

Since this file is a configuration utility file coordinating multiple processes (scanning, spec generation, route generation), a **flowchart** is appropriate to visualize the workflow.

flowchart TD
    A[tsoa.json Configuration] --> B[Start at entryFile (src/app.ts)]
    B --> C{Scan controller files}
    C -->|Match src/**/controller.ts| D[Parse Controllers]
    C -->|Ignore **/node_modules/**, **/dist/**| E[Skip Ignored Paths]
    D --> F[Generate OpenAPI Spec (v3) in src/]
    D --> G[Generate Routes in src/]
    F --> H[Output: openapi.json (or similar)]
    G --> I[Output: routes files]
    H --> J[Used for API docs, validation, client generation]
    I --> K[Used by server to handle HTTP requests]

Summary

This configuration ensures tsoa performs a strict, clean generation of API specs and routes, tightly integrated with the project's folder structure and coding conventions.

If you need further integration guidance or examples for tsoa decorators usage, please let me know!