tsoa is a code generator that builds OpenAPI-compliant REST APIs using TypeScript and Node.
The tool solves the problem of keeping API documentation in sync with implementation by using TypeScript type annotations as the single source of truth. It generates valid OpenAPI specifications (versions 2.0 or 3.0) directly from TypeScript controllers and models, extracting paths, parameter definitions, and type information automatically. Request payloads are validated at runtime against the generated schema. Routes are generated for popular middleware frameworks including Express, Hapi, and Koa, with support for additional frameworks through custom Handlebars templates. The approach minimizes boilerplate by relying on TypeScript's type system and decorators for metadata, with jsDoc used only for textual descriptions.
Developers should choose this tool when building Node-based REST APIs where keeping documentation synchronized with code matters and TypeScript is already in use. It suits projects that value type safety and want to avoid manually maintaining OpenAPI specifications. The tool works best with Express, Hapi, or Koa, though other middleware can be supported through templates. Teams should be aware that while OpenAPI 3 provides more expressive schema syntax and reduces validation divergence, OpenAPI 2.0 is also supported if needed for compatibility reasons.
The project maintains a substantial base of real-world adopters, as evidenced by the fact that nearly all open issues originate from outside users rather than the core team. Responses to issues and pull requests typically arrive within one to two weeks. Work in the issue tracker centers on bug fixes, feedback collection, and enhancement requests.
