Overview The SpecConfig interface defines configuration options for generating OpenAPI specifications from your tsoa controllers. It controls the output format, API metadata, security definitions, and more.
Required Properties outputDirectory Directory where the generated OpenAPI specification file will be written.
{ "spec" : { "outputDirectory" : "dist" } }
Generates: dist/swagger.json (or dist/swagger.yaml if yaml: true)
Optional Properties specFileBaseName Base name for the generated specification file (without extension).
{ "spec" : { "outputDirectory" : "dist" , "specFileBaseName" : "openapi" } }
Generates: dist/openapi.json
yaml Generate YAML output instead of JSON.
{ "spec" : { "outputDirectory" : "dist" , "yaml" : true } }
Generates: dist/swagger.yaml
specVersion Major OpenAPI version to generate.
2: Swagger 2.0 (deprecated)3: OpenAPI 3.0.x (recommended)3.1: OpenAPI 3.1.x (latest) { "spec" : { "outputDirectory" : "dist" , "specVersion" : 3 } }
name API name. Defaults to the name field from package.json.
{ "spec" : { "outputDirectory" : "dist" , "name" : "E-Commerce API" } }
version API version. Defaults to the version field from package.json.
{ "spec" : { "outputDirectory" : "dist" , "version" : "2.1.0" } }
description API description. Defaults to the description field from package.json.
{ "spec" : { "outputDirectory" : "dist" , "description" : "RESTful API for managing e-commerce operations" } }
license API license. Defaults to the license field from package.json.
{ "spec" : { "outputDirectory" : "dist" , "license" : "MIT" } }
termsOfService Link to the terms of service. Must be a valid URL.
{ "spec" : { "outputDirectory" : "dist" , "termsOfService" : "https://example.com/terms" } }
Contact information for the API.
Show Contact Object Properties
Contact name. Defaults to npm package author.
Contact email. Defaults to npm package author email.
Contact URL. Defaults to npm package author URL.
{ "spec" : { "outputDirectory" : "dist" , "contact" : { "name" : "API Support Team" , "email" : "[email protected] " , "url" : "https://example.com/support" } } }
Server Configuration host API host (for OpenAPI 2.0). Example: localhost:3000 or api.example.com
{ "spec" : { "outputDirectory" : "dist" , "specVersion" : 2 , "host" : "api.example.com" } }
servers API servers (for OpenAPI 3.x). Example: ["https://api.example.com", "https://staging.api.example.com"]
{ "spec" : { "outputDirectory" : "dist" , "specVersion" : 3 , "servers" : [ "https://api.example.com" , "https://staging.api.example.com" ] } }
basePath Base API path prefix. Example: /v1 results in https://api.example.com/v1
{ "spec" : { "outputDirectory" : "dist" , "basePath" : "/api/v2" } }
disableBasePathPrefixSlash disableBasePathPrefixSlash
Disable the leading slash in base path (OpenAPI 3.x only). When true, basePath: "v1" becomes https://api.comv1 instead of https://api.com/v1
{ "spec" : { "outputDirectory" : "dist" , "specVersion" : 3 , "disableBasePathPrefixSlash" : true } }
schemes schemes
('http' | 'https' | 'ws' | 'wss')[]
Transfer protocols supported by the API (OpenAPI 2.0).
{ "spec" : { "outputDirectory" : "dist" , "specVersion" : 2 , "schemes" : [ "https" , "http" ] } }
Security Configuration securityDefinitions Security scheme definitions for the API. Keys are security scheme names, values are security scheme objects.
{ "spec" : { "outputDirectory" : "dist" , "securityDefinitions" : { "bearer" : { "type" : "http" , "scheme" : "bearer" , "bearerFormat" : "JWT" }, "api_key" : { "type" : "apiKey" , "name" : "X-API-Key" , "in" : "header" }, "oauth2" : { "type" : "oauth2" , "flows" : { "authorizationCode" : { "authorizationUrl" : "https://example.com/oauth/authorize" , "tokenUrl" : "https://example.com/oauth/token" , "scopes" : { "read:users" : "Read user data" , "write:users" : "Modify user data" , "admin" : "Administrative access" } } } } } } }
Show Common Security Schemes
HTTP Bearer (JWT) { "bearer" : { "type" : "http" , "scheme" : "bearer" , "bearerFormat" : "JWT" } }
{ "api_key" : { "type" : "apiKey" , "name" : "X-API-Key" , "in" : "header" } }
API Key (Query) { "api_key" : { "type" : "apiKey" , "name" : "api_key" , "in" : "query" } }
HTTP Basic Auth { "basic" : { "type" : "http" , "scheme" : "basic" } }
OAuth2 { "oauth2" : { "type" : "oauth2" , "flows" : { "authorizationCode" : { "authorizationUrl" : "https://example.com/oauth/authorize" , "tokenUrl" : "https://example.com/oauth/token" , "scopes" : { "read" : "Read access" , "write" : "Write access" } } } } }
OpenID Connect { "openid" : { "type" : "openIdConnect" , "openIdConnectUrl" : "https://example.com/.well-known/openid-configuration" } }
rootSecurity Default security requirements applied to all endpoints. Can be overridden with @Security or @NoSecurity decorators.
{ "spec" : { "outputDirectory" : "dist" , "securityDefinitions" : { "bearer" : { "type" : "http" , "scheme" : "bearer" } }, "rootSecurity" : [ { "bearer" : [] } ] } }
Tag definitions with descriptions and external documentation.
{ "spec" : { "outputDirectory" : "dist" , "tags" : [ { "name" : "Users" , "description" : "User management operations" , "externalDocs" : { "description" : "User API Documentation" , "url" : "https://docs.example.com/users" } }, { "name" : "Products" , "description" : "Product catalog management" }, { "name" : "Orders" , "description" : "Order processing and fulfillment" } ] } }
Advanced Options spec Additional properties to merge into the generated specification. Generated properties always take precedence.
{ "spec" : { "outputDirectory" : "dist" , "spec" : { "x-api-id" : "my-custom-api" , "x-logo" : { "url" : "https://example.com/logo.png" }, "externalDocs" : { "description" : "Full Documentation" , "url" : "https://docs.example.com" } } } }
specMerging specMerging
'immediate' | 'recursive' | 'deepmerge'
default: "immediate"
Strategy for merging the spec object with generated specification.
'immediate': Only merge top-level properties'recursive': Deep merge using merge package'deepmerge': Deep merge using ts-deepmerge package { "spec" : { "outputDirectory" : "dist" , "specMerging" : "recursive" } }
operationIdTemplate operationIdTemplate
string
default: "{{titleCase method.name}}"
Handlebars template for generating operation IDs. Context:
controllerName: Controller class namemethod: Method metadata object { "spec" : { "outputDirectory" : "dist" , "operationIdTemplate" : "{{controllerName}}_{{method.name}}" } }
Example output: // Controller: UserController // Method: getUser // Default template: "GetUser" // Custom template: "UserController_getUser"
xEnumVarnames Enable x-enum-varnames extension for enum values. Useful for code generators that need the original enum member names.
{ "spec" : { "outputDirectory" : "dist" , "xEnumVarnames" : true } }
Example: enum UserRole { Administrator = 'admin' , Editor = 'editor' , Viewer = 'viewer' } // Generated OpenAPI with xEnumVarnames: true { "type" : "string" , "enum" : [ "admin" , "editor" , "viewer" ], "x-enum-varnames" : [ "Administrator" , "Editor" , "Viewer" ] }
useTitleTagsForInlineObjects
Set titles for inline objects in responses and request bodies. Helps generate more consistent client code.
{ "spec" : { "outputDirectory" : "dist" , "useTitleTagsForInlineObjects" : true } }
Complete Examples Minimal Configuration { "spec" : { "outputDirectory" : "dist" , "specVersion" : 3 } }
Development Configuration { "spec" : { "outputDirectory" : "dist" , "specVersion" : 3 , "name" : "My API" , "version" : "1.0.0" , "description" : "API for development" , "host" : "localhost:3000" , "schemes" : [ "http" ] } }
Production Configuration { "spec" : { "outputDirectory" : "public/api-docs" , "specFileBaseName" : "openapi" , "yaml" : true , "specVersion" : 3 , "name" : "E-Commerce API" , "version" : "2.1.0" , "description" : "Production API for e-commerce platform" , "license" : "MIT" , "termsOfService" : "https://example.com/terms" , "contact" : { "name" : "API Support" , "email" : "[email protected] " , "url" : "https://example.com/support" }, "servers" : [ "https://api.example.com" , "https://staging.api.example.com" ], "basePath" : "/v2" , "securityDefinitions" : { "bearer" : { "type" : "http" , "scheme" : "bearer" , "bearerFormat" : "JWT" } }, "rootSecurity" : [ { "bearer" : [] } ], "tags" : [ { "name" : "Users" , "description" : "User management" }, { "name" : "Products" , "description" : "Product catalog" } ] } }
See Also