tsoa.json

Overview

The `tsoa.json` file serves as the primary configuration file for the [tsoa](https://github.com/lukeautry/tsoa) framework, which is a TypeScript OpenAPI (Swagger) and routing tool that helps generate routes and API documentation automatically based on TypeScript source code annotations. This file defines the conventions and settings for how tsoa scans the project, generates OpenAPI specifications, and produces routing files.

Key functionalities of this file include:

• Specifying the entry point for the application (the main TypeScript file).

• Setting rules for how tsoa handles additional properties on objects.

• Defining the file globs for controller files to be scanned.

• Configuring the output location and OpenAPI specification version.

• Defining where generated route files will be placed.

• Specifying paths to exclude from scanning (e.g., node_modules, dist).

This configuration ensures that tsoa can correctly parse the project structure, generate OpenAPI compliant documentation, and produce route files that integrate seamlessly with the application.

Detailed Explanation

Top-Level Properties

Property Details and Usage

entryFile: "src/app.ts"

• Purpose: Defines the main TypeScript file where the tsoa scanning begins. This file should include or import all controllers and models used in the application.

• Usage Example: If your main app file is src/main.ts, you would set "entryFile": "src/main.ts".

noImplicitAdditionalProperties: "throw-on-extras"

• Purpose: Enforces strict validation on object properties by throwing errors when additional properties (not declared in the model) are received.

• Options:

  • "ignore": Ignores additional properties.

  • "silently-remove-extras": Removes additional properties without throwing.

  • "throw-on-extras": Throws errors on additional properties (used here).

• Effect: Ensures API inputs strictly conform to defined models, enhancing API safety.

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

• Purpose: Specifies the file patterns that tsoa uses to locate controller files.

• Effect: tsoa will recursively scan all files named controller.ts under src directory.

• Usage Example: To include all controllers with .controller.ts suffix, one could use "src/**/*.controller.ts".

spec

• Purpose: Contains configuration for OpenAPI specification generation.

• Sub-properties:

  • outputDirectory: "src": Specifies that the OpenAPI spec files will be generated inside the src folder.

  • specVersion: 3: Indicates the use of OpenAPI Specification version 3.

routes

• Purpose: Configuration related to route file generation.

• Sub-properties:

  • routesDir: "src": Specifies that the routes generated by tsoa will be saved into the src folder.

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

• Purpose: Specifies files and directories to exclude from tsoa scans.

• Effect: Prevents scanning of dependencies and build output folders, improving performance and avoiding irrelevant files.

Important Implementation Details

• tsoa scanning process: Using the entryFile as the root, tsoa performs static analysis by traversing the TypeScript AST (Abstract Syntax Tree) to find all referenced controllers and models matching the patterns in controllerPathGlobs.

• Validation policy: The setting noImplicitAdditionalProperties: "throw-on-extras" enables strict runtime validation in generated route handlers to ensure that clients do not send unexpected properties in API requests.

• OpenAPI Spec Generation: tsoa automatically creates a fully compliant OpenAPI 3 specification, which can be used for generating API docs or client SDKs.

• Route Generation: tsoa creates route files with Express (or other frameworks) route handlers using the annotations found in controllers.

• Exclusion patterns: The ignore array uses glob patterns to avoid scanning irrelevant files, which is critical for performance and accuracy.

Interaction with Other Parts of the System

• Entry File (src/app.ts): This is the starting point for tsoa's static analysis. It should import or reference the controllers.

• Controllers (src/**/controller.ts): The controllers define the API endpoints with decorators such as @Route, @Get, @Post, etc. tsoa reads these files to generate OpenAPI docs and route handlers.

• Generated OpenAPI Spec (src/): The generated specification JSON or YAML files are placed here for use by API documentation tools or client code generators.

• Generated Routes (src/): The generated route files integrate with the application server setup, typically imported in src/app.ts or similar to plug routes into the Express app.

• Build Tools and Runtime: The ignore paths ensure that the build artifacts and node_modules are not processed by tsoa, keeping the scanning focused on source files only.

This configuration file is essential for aligning tsoa's behavior with the project structure and ensuring that API documentation and code generation stay consistent with the TypeScript source code.

Visual Diagram

Below is a flowchart summarizing the workflow and components configured in the `tsoa.json` file:

flowchart TD
    A[Start: tsoa CLI] --> B[Reads tsoa.json Configuration]
    B --> C[Uses "entryFile" (src/app.ts) as root]
    C --> D[Scans controller files (src/**/controller.ts)]
    D --> E{Excludes files matching ignore patterns?}
    E -- Yes --> F[Skip files]
    E -- No --> G[Parse Controllers and Models]
    G --> H[Generate OpenAPI Spec (v3) in src/]
    G --> I[Generate Routes in src/]
    H & I --> J[App imports generated routes and spec]
    J --> K[Application runs with validated routes and docs]

Summary

The `tsoa.json` file is a lightweight but critical configuration file that guides tsoa in scanning the TypeScript project, generating OpenAPI documentation, and producing route files that integrate with the app. It specifies:

• The entry point to start scanning.

• How to handle unexpected properties on models.

• Where to find controllers.

• Where to output generated files.

• What files/folders to exclude.

By configuring these options, developers ensure that tsoa can automate much of the repetitive work of API documentation and routing, keeping the API consistent, validated, and well-documented.