- TypeScript controllers and models as the single source of truth for your API
- A valid OpenAPI (formerly Swagger) spec (2.0 or 3.0 if you choose 😍) is generated from your controllers and models, including:
- Paths (e.g. GET /users)
- Definitions based on TypeScript interfaces (models)
- Parameters/model properties marked as required or optional based on TypeScript (e.g. myProperty?: string is optional in the OpenAPI spec)
- jsDoc supported for object descriptions (most other metadata can be inferred from TypeScript types)
- Routes are generated for middleware of choice
- Express, Hapi, and Koa currently supported, other middleware can be supported using a simple handlebars template
- Validate request payloads
- Rely on TypeScript type annotations to generate API metadata if possible
- If regular type annotations aren't an appropriate way to express metadata, use decorators
- Use jsdoc for pure text metadata (e.g. endpoint descriptions)
- Minimize boilerplate
- Models are best represented by interfaces (pure data structures), but can also be represented by classes
- Runtime validation of tsoa should behave as closely as possible to the specifications that the generated OpenAPI 2/3 schema describes. Any differences in validation logic are clarified by logging warnings during the generation of the OpenAPI Specification (OAS) and/or the routes.
- Please note that by enabling OpenAPI 3 you minimize the chances of divergent validation logic since OpenAPI 3 has a more expressive schema syntax.
@tsoa/runtime does not install a web framework. Its framework packages are optional peer dependencies, so install the ones for the framework you use:
| Framework | Packages |
|---|---|
| Express | express, @types/express (4 or 5) |
| Koa | koa, @types/koa (2 or 3) |
| Hapi | @hapi/hapi, @hapi/boom |
The generated Hapi routes import boomify and isBoom from @hapi/boom. @hapi/hapi depends on it, but list it in your own package.json as well: with pnpm or another strict layout, the routes cannot resolve it otherwise.
Each framework's template service has its own entry point. The @tsoa/runtime and tsoa roots do not export them, so custom route templates (routes.middlewareTemplate) and classes that extend a template service import them from the subpath:
import { ExpressTemplateService } from '@tsoa/runtime/express';
import { HapiTemplateService } from '@tsoa/runtime/hapi';
import { KoaTemplateService } from '@tsoa/runtime/koa';Check out the guides
See example controllers in the tests
See example models in the tests
To contribute (via a PR), please first see the Contributing Guide
tsoa wants additional maintainers! The library has increased in popularity and has quite a lot of pull requests and issues. Please post in this issue if you're willing to take on the role of a maintainer.