tsoa.json

Overview

`tsoa.json` is a configuration file used by the **tsoa** framework, a TypeScript OpenAPI (Swagger) generator and routing tool for Node.js applications. This file defines the settings and parameters that guide how tsoa generates API routes, OpenAPI specifications, and integrates with the existing TypeScript codebase.

Primarily, `tsoa.json` specifies:

• The entry point of the application (entryFile).

• How to handle additional properties in API models (noImplicitAdditionalProperties).

• Where to locate controller files (controllerPathGlobs).

• Settings for OpenAPI specification output (spec).

• Routes generation settings (routes).

• Files or directories to ignore during the generation process (ignore).

This file enables seamless automation of API documentation and routing by linking TypeScript controllers to generated OpenAPI specs and route files, facilitating maintainable and consistent API development.

Detailed Explanation of Properties

1. entryFile: string

Specifies the main entry point of the application, which tsoa uses as the root for analyzing the project and resolving imports.

• Example: "src/app.ts"

• Usage: tsoa begins scanning for controllers and models starting from this file.

2. noImplicitAdditionalProperties: string

Controls the behavior when additional properties not defined in the model interfaces appear in incoming requests.

• Possible values:

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

  • "ignore" — Ignores extra properties.

  • "silently-remove-extras" — Removes extra properties silently.

• Configured value: "throw-on-extras"

• Effect: Enforces strict validation to prevent unexpected data in requests.

3. controllerPathGlobs: string[]

An array of glob patterns specifying file paths where tsoa should look for controller classes.

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

• Effect: All TypeScript files matching this pattern will be scanned for tsoa controller decorators.

4. spec: object

Settings related to the OpenAPI specification generation.

• Properties:

  • outputDirectory: string — Directory where the generated OpenAPI spec files will be saved.

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

• Configured values:

  • "outputDirectory": "src"

  • "specVersion": 3

• Effect: Controls where and how the OpenAPI specification is output.

5. routes: object

Settings related to route generation.

• Properties:

  • routesDir: string — Directory where the generated routing files will be placed.

• Configured value: "src"

• Effect: Specifies the folder for tsoa-generated route files that link controllers to express (or other frameworks) routes.

6. ignore: string[]

An array of glob patterns specifying files or directories that tsoa should ignore during scanning.

• Configured values: ["**/node_modules/**", "**/dist/**"]

• Effect: Excludes common build and dependency folders from tsoa processing.

Implementation Details and Algorithms

`tsoa.json` is a static JSON configuration file and does not contain executable code or algorithms itself. Instead, it is consumed by the tsoa CLI and API during the build or generation steps:

• Controller scanning: tsoa uses the controllerPathGlobs to recursively find controller files decorated with tsoa decorators (@Route, @Get, @Post, etc.).

• Model validation: The noImplicitAdditionalProperties setting controls how tsoa generates validation logic in the OpenAPI spec and runtime.

• Spec generation: Based on the controllers and models, tsoa generates OpenAPI 3-compliant JSON or YAML files in the spec.outputDirectory.

• Route generation: tsoa produces route files that bind controller methods to HTTP endpoints in the routes.routesDir directory.

• Ignore patterns: The ignore array ensures that irrelevant files (e.g., external modules, build output) are excluded to optimize scanning.

Interaction with Other Parts of the System

• Entry File (src/app.ts): This file is the root of the application and likely sets up the web server, imports controllers, and configures middleware. tsoa uses it as the starting point for dependency resolution.

• Controller Files: Matched by controllerPathGlobs (e.g., src/**/controller.ts), these files contain the API endpoint definitions using tsoa decorators.

• Generated Spec and Routes: tsoa outputs OpenAPI specification files and route configuration files in the src directory, which are then used by the application to serve API documentation and route requests.

• Build Process: This configuration is typically used as part of the build or pre-build scripts that run tsoa commands such as tsoa spec and tsoa routes to generate up-to-date API artifacts.

Usage Example

Assuming you have this configuration, you would run tsoa commands like:

tsoa spec

This generates an OpenAPI 3 specification inside the `src` directory.

tsoa routes

This generates route files inside the `src` directory, which you can then import in your `src/app.ts` to register routes with your Express or Koa server.

Mermaid Diagram: Configuration Structure Flowchart

flowchart TD
    A[tsoa.json Configuration]
    A --> B[Entry File: "src/app.ts"]
    A --> C[Controller Path Globs: "src/**/controller.ts"]
    A --> D[Spec Generation]
    D --> D1[Output Directory: "src"]
    D --> D2[OpenAPI Spec Version: 3]
    A --> E[Route Generation]
    E --> E1[Routes Directory: "src"]
    A --> F[Additional Properties Policy: "throw-on-extras"]
    A --> G[Ignore Patterns]
    G --> G1["**/node_modules/**"]
    G --> G2["**/dist/**"]

Summary

`tsoa.json` is a vital configuration file for projects using the tsoa framework to automate API documentation and routing. By defining the entry point, controller locations, validation rules, and output directories, it orchestrates the generation of OpenAPI specs and route bindings—ensuring that the API remains consistent, well-documented, and easy to maintain.

This file works closely with:

• The application entry point (src/app.ts).

• Controller source files.

• Generated OpenAPI specification files.

• Generated route files used by the server framework.

Together, these components enable a smooth developer experience for building and documenting RESTful APIs in TypeScript.