tsoa.json Reference

This page documents every configuration option available in tsoa configuration files. For practical examples and guidance, see the Configuration Guide.

Root Configuration

entryFile

string

The entry point to your API. This file should import (directly or indirectly) all controller files.

"entryFile": "src/app.ts"

Either entryFile or controllerPathGlobs is required. Cannot use both.

controllerPathGlobs

string[]

Array of glob patterns pointing to controller files. Alternative to entryFile that allows direct file selection.

"controllerPathGlobs": [
  "src/controllers/**/*Controller.ts",
  "src/modules/**/controllers/*.ts"
]

Supported glob patterns:

* - Matches any characters except /
** - Matches any characters including /
{a,b} - Matches a or b
[abc] - Matches any character in the set

spec

SpecConfig

required

Configuration for OpenAPI specification generation. See Spec Configuration below.

routes

RoutesConfig

required

Configuration for route handler generation. See Routes Configuration below.

noImplicitAdditionalProperties

enum

Controls validation behavior for extra properties in request bodies.

Show options

ignore

string

default:true

Allow extra properties (no validation)

silently-remove-extras

string

Remove extra properties without error

throw-on-extras

string

Reject requests with 400 error when extra properties present

"noImplicitAdditionalProperties": "throw-on-extras"

ignore

string[]

Array of glob patterns for directories/files to ignore during TypeScript scanning.

"ignore": [
  "**/node_modules/**",
  "**/test/**",
  "**/*.spec.ts"
]

compilerOptions

Record<string, unknown>

TypeScript compiler options to use during generation. Merged with options from tsconfig.json.

"compilerOptions": {
  "target": "ES2020",
  "module": "commonjs",
  "esModuleInterop": true,
  "skipLibCheck": true,
  "strictNullChecks": true
}

defaultNumberType

enum

default:"double"

Default OpenAPI type for TypeScript number when no type annotation present.Options: "double", "float", "integer", "long"

"defaultNumberType": "integer"

multerOpts

MulterOptions

Deprecated since v6.4.0. Pass multer options to RegisterRoutes() instead.

Multer configuration for file uploads.

"multerOpts": {
  "dest": "/tmp/uploads"
}

Spec Configuration

All properties under the spec key in your configuration:

Required Properties

spec.outputDirectory

string

required

Directory where the OpenAPI specification file will be written.

"spec": {
  "outputDirectory": "dist/docs"
}

Version and Format

spec.specVersion

number

default:2

Major OpenAPI version to generate.Supported values:

2 - OpenAPI 2.0 (Swagger)
3 - OpenAPI 3.0.x
3.1 - OpenAPI 3.1.x

"spec": {
  "specVersion": 3
}

spec.yaml

boolean

default:false

Generate YAML format instead of JSON.

"spec": {
  "yaml": true
}

spec.specFileBaseName

string

default:"swagger"

Base name of the output file (without extension).

"spec": {
  "specFileBaseName": "openapi"
}

With yaml: true, generates openapi.yaml. Otherwise, generates openapi.json.

API Metadata

spec.name

string

API name. Defaults to name from package.json.

"spec": {
  "name": "My API"
}

spec.version

string

API version. Defaults to version from package.json.

"spec": {
  "version": "2.0.0"
}

spec.description

string

API description. Defaults to description from package.json.

"spec": {
  "description": "A comprehensive REST API for managing resources"
}

spec.license

string

API license. Defaults to license from package.json.

"spec": {
  "license": "MIT"
}

spec.termsOfService

string

Link to terms of service. Must be a valid URL.

"spec": {
  "termsOfService": "https://example.com/terms"
}

spec.contact

object

Contact information for the API.

Show properties

name

string

Contact name. Defaults to author name from package.json.

string

Contact email. Defaults to author email from package.json.

url

string

Contact URL. Defaults to author URL from package.json.

"spec": {
  "contact": {
    "name": "API Support",
    "email": "[email protected]",
    "url": "https://example.com/support"
  }
}

Server Configuration

spec.host

string

API host (OpenAPI 2.0 only). Format: hostname[:port]

"spec": {
  "specVersion": 2,
  "host": "api.example.com"
}

spec.basePath

string

default:"/"

Base path prepended to all API routes.

"spec": {
  "basePath": "/api/v1"
}

spec.schemes

string[]

Transfer protocols (OpenAPI 2.0 only).Values: "http", "https", "ws", "wss"

"spec": {
  "specVersion": 2,
  "schemes": ["https", "http"]
}

spec.servers

string[]

Server URLs (OpenAPI 3.x only). Can include variables.

"spec": {
  "specVersion": 3,
  "servers": [
    "https://api.example.com/v1",
    "https://staging.example.com/v1"
  ]
}

spec.disableBasePathPrefixSlash

boolean

default:false

Remove leading slash from basePath in server URLs (OpenAPI 3.x only).

"spec": {
  "basePath": "v1",
  "disableBasePathPrefixSlash": true
}

Generates: https://api.example.comv1 instead of https://api.example.com/v1

Security Configuration

spec.securityDefinitions

object

Security schemes available in the API. Keys are security scheme names.

"spec": {
  "securityDefinitions": {
    "jwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}

spec.rootSecurity

array

Default security requirements applied to all endpoints. Can be overridden with @Security or @NoSecurity decorators.

"spec": {
  "securityDefinitions": {
    "jwt": { "type": "http", "scheme": "bearer" }
  },
  "rootSecurity": [
    { "jwt": [] }
  ]
}

Requires JWT authentication on all endpoints unless overridden.

Tags and Organization

spec.tags

array

Global tag definitions for API organization.

"spec": {
  "tags": [
    {
      "name": "Users",
      "description": "User management endpoints"
    },
    {
      "name": "Products",
      "description": "Product catalog operations"
    }
  ]
}

Advanced Options

spec.operationIdTemplate

string

default:"{{titleCase method.name}}"

Handlebars template for generating operation IDs.Available context:

controllerName - Controller class name
method - Method metadata object
method.name - Method name

Helpers:

titleCase - Converts to title case
kebabCase - Converts to kebab-case

"spec": {
  "operationIdTemplate": "{{controllerName}}_{{method.name}}"
}

spec.spec

unknown

Custom OpenAPI properties to merge into the generated spec.

"spec": {
  "spec": {
    "x-custom-property": "custom value",
    "externalDocs": {
      "description": "Find more info here",
      "url": "https://example.com/docs"
    }
  }
}

spec.specMerging

enum

default:"immediate"

Strategy for merging spec property with generated specification.

Show options

immediate

string

Merge only top-level properties (default)

recursive

string

Deep merge all nested objects

deepmerge

string

Deep merge using ts-deepmerge (concatenates arrays)

"spec": {
  "specMerging": "recursive"
}

spec.xEnumVarnames

boolean

default:false

Add x-enum-varnames extension for better enum handling in code generators.

"spec": {
  "xEnumVarnames": true
}

spec.useTitleTagsForInlineObjects

boolean

default:false

Generate titles for inline objects in requests/responses. Improves code generation consistency.

"spec": {
  "useTitleTagsForInlineObjects": true
}

Routes Configuration

All properties under the routes key in your configuration:

Required Properties

routes.routesDir

string

required

Directory where the generated routes file will be written.

"routes": {
  "routesDir": "src/generated"
}

Middleware Configuration

routes.middleware

enum

Web framework to generate routes for.Options: "express", "koa", "hapi"

"routes": {
  "middleware": "express"
}

routes.middlewareTemplate

string

Path to custom middleware template. Allows complete customization of generated routes.

"routes": {
  "middlewareTemplate": "./templates/custom-routes.hbs"
}

Output Configuration

routes.routesFileName

string

default:"routes.ts"

Name of the generated routes file.

"routes": {
  "routesFileName": "tsoa-routes.ts"
}

routes.basePath

string

default:"/"

Base path prepended to all routes.

"routes": {
  "basePath": "/api/v1"
}

routes.noWriteIfUnchanged

boolean

default:false

Skip writing routes file if content unchanged. Useful for watch mode.

"routes": {
  "noWriteIfUnchanged": true
}

Module Integration

routes.authenticationModule

string

Path to module exporting authentication function.

"routes": {
  "authenticationModule": "./auth/authentication.ts"
}

Module must export expressAuthentication, koaAuthentication, or hapiAuthentication:

export async function expressAuthentication(
  request: Request,
  securityName: string,
  scopes?: string[]
): Promise<any> {
  // Return user object or throw error
}

routes.iocModule

string

Path to IoC container module.

"routes": {
  "iocModule": "./ioc/container.ts"
}

Module must export iocContainer:

import { Container } from 'inversify';
export const iocContainer = new Container();

ES Modules Support

routes.esm

boolean

default:false

Generate imports with .js extensions for ES modules.

"routes": {
  "esm": true
}

Generates:

import { UserController } from './controllers/userController.js';

routes.rewriteRelativeImportExtensions

boolean

default:false

Keep .ts extensions in imports for TypeScript 5.7+ rewriteRelativeImportExtensions feature.

"routes": {
  "rewriteRelativeImportExtensions": true
}

Validation Options

routes.bodyCoercion

boolean

default:true

Automatically coerce body parameters to expected types.

"routes": {
  "bodyCoercion": true
}

When enabled, strings are converted to numbers, booleans, etc. when the type signature expects them.

Example Configurations

Minimal Configuration

{
  "entryFile": "src/app.ts",
  "spec": {
    "outputDirectory": "dist"
  },
  "routes": {
    "routesDir": "src"
  }
}

Complete Configuration

{
  "entryFile": "src/server.ts",
  "controllerPathGlobs": ["src/controllers/**/*.ts"],
  "noImplicitAdditionalProperties": "throw-on-extras",
  "ignore": ["**/node_modules/**", "**/test/**"],
  "defaultNumberType": "double",
  "compilerOptions": {
    "target": "ES2020",
    "esModuleInterop": true
  },
  "spec": {
    "outputDirectory": "docs",
    "specVersion": 3,
    "specFileBaseName": "openapi",
    "yaml": true,
    "name": "My API",
    "version": "1.0.0",
    "description": "A comprehensive REST API",
    "license": "MIT",
    "contact": {
      "name": "API Support",
      "email": "[email protected]"
    },
    "servers": ["https://api.example.com"],
    "basePath": "/v1",
    "securityDefinitions": {
      "jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "rootSecurity": [{"jwt": []}],
    "tags": [
      {"name": "Users", "description": "User management"}
    ],
    "operationIdTemplate": "{{controllerName}}_{{method.name}}",
    "xEnumVarnames": true
  },
  "routes": {
    "routesDir": "src/generated",
    "routesFileName": "routes.ts",
    "middleware": "express",
    "basePath": "/v1",
    "authenticationModule": "./auth/authentication.ts",
    "iocModule": "./ioc/container.ts",
    "esm": false,
    "bodyCoercion": true,
    "noWriteIfUnchanged": true
  }
}

Type Definitions

tsoa exports TypeScript types for configuration:

import type { Config, SpecConfig, RoutesConfig } from 'tsoa';

const config: Config = {
  entryFile: 'src/app.ts',
  spec: {
    outputDirectory: 'dist'
  },
  routes: {
    routesDir: 'src'
  }
};

export default config;

Getting Started

Core Concepts

CLI & Configuration

Guides

Advanced

Migration

tsoa.json Reference

Root Configuration

Spec Configuration

Required Properties

Version and Format

API Metadata

Server Configuration

Security Configuration

Tags and Organization

Advanced Options

Routes Configuration

Required Properties

Middleware Configuration

Output Configuration

Module Integration

ES Modules Support

Validation Options

Example Configurations

Minimal Configuration

Complete Configuration

Type Definitions

Next Steps

Configuration Guide

CLI Commands

Build docs developers (and LLMs) love

Getting Started

Core Concepts

CLI & Configuration

Guides

Advanced

Migration

​Root Configuration

​Spec Configuration

​Required Properties

​Version and Format

​API Metadata

​Server Configuration

​Security Configuration

​Tags and Organization

​Advanced Options

​Routes Configuration

​Required Properties

​Middleware Configuration

​Output Configuration

​Module Integration

​ES Modules Support

​Validation Options

​Example Configurations

​Minimal Configuration

​Complete Configuration

​Type Definitions

​Next Steps

Configuration Guide

CLI Commands

Build docs developers (and LLMs) love

Root Configuration

Spec Configuration

Required Properties

Version and Format

API Metadata

Server Configuration

Security Configuration

Tags and Organization

Advanced Options

Routes Configuration

Required Properties

Middleware Configuration

Output Configuration

Module Integration

ES Modules Support

Validation Options

Example Configurations

Minimal Configuration

Complete Configuration

Type Definitions

Next Steps