tsoa

What is tsoa?

tsoa is a TypeScript framework for building RESTful APIs. It provides tools to automatically generate OpenAPI documentation and route handlers based on TypeScript interfaces and decorators.

What are tsoa's main functionalities?

Automatic Route Generation

tsoa allows you to define your API routes using TypeScript decorators. The above code defines a route '/users' that returns a list of users.

import { Controller, Get, Route } from 'tsoa';

@Route('users')
export class UserController extends Controller {
  @Get()
  public async getUsers(): Promise<User[]> {
    return [{ id: 1, name: 'John Doe' }];
  }
}

OpenAPI Specification Generation

tsoa can automatically generate OpenAPI specifications and route handlers based on your TypeScript code. This helps in keeping your API documentation up-to-date with your code.

import { generateRoutes, generateSpec } from 'tsoa';

const app = express();

// Generate OpenAPI spec
generateSpec({
  entryFile: './src/server.ts',
  outputDirectory: './dist',
  specVersion: 3
});

// Generate routes
generateRoutes({
  entryFile: './src/server.ts',
  routesDir: './dist'
});

Request Validation

tsoa provides built-in request validation. The above code demonstrates how to validate query parameters using decorators.

import { Controller, Get, Route, Query } from 'tsoa';

@Route('users')
export class UserController extends Controller {
  @Get()
  public async getUsers(@Query() age: number): Promise<User[]> {
    // Validate the 'age' query parameter
    if (age < 0) {
      throw new Error('Age must be a positive number');
    }
    return [{ id: 1, name: 'John Doe', age }];
  }
}

Other packages similar to tsoa

express-openapi

express-openapi is a framework for building APIs with Express and OpenAPI. It allows you to define your API using OpenAPI specifications and automatically generates route handlers. Compared to tsoa, express-openapi focuses more on OpenAPI specifications and less on TypeScript integration.

nest

NestJS is a progressive Node.js framework for building efficient, reliable, and scalable server-side applications. It uses TypeScript and provides a lot of built-in features like dependency injection, modular architecture, and more. While tsoa focuses on generating OpenAPI documentation and route handlers, NestJS offers a more comprehensive solution for building server-side applications.

swagger-jsdoc

swagger-jsdoc is a library that allows you to integrate JSDoc comments with Swagger (OpenAPI) documentation. It generates OpenAPI documentation based on JSDoc comments in your code. Unlike tsoa, swagger-jsdoc does not provide route generation or TypeScript integration.

README

tsoa

Pronounced so·uh

OpenAPI-compliant REST APIs using TypeScript and Node

Goal

• 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

Philosophy

• 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.

Getting Started

• Documentation
• API Reference
• Getting started guide

Examples

Check out the guides

See example controllers in the tests

See example models in the tests

Help wanted

Contributing code

To contribute (via a PR), please first see the Contributing Guide

Becoming a maintainer

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.