tspec

Tspec

Type-driven API Documentation library for TypeScript.

Automatically parses your TypeScript types and generates up-to-date OpenAPI specification with beautiful Swagger UI.

Why tspec?

• Code First: Rely on TypeScript type and JSDoc to generate OpenAPI Specification.
• Easy to learn: No need to learn new OpenAPI Spec syntax. Just use TypeScript types.
• Easy to use: Only few lines of code are needed to generate OpenAPI Specification.
• Flexible: You can use any framework you want. It doesn't impose any framework-specific constraints.
• NestJS Support: Generate OpenAPI spec directly from NestJS controllers with --nestjs flag.

Installation

npm install tspec

Usage

import { Tspec } from "tspec";

/** Schema description defined by JSDoc */
interface Book {
  /** Field description defined by JSDoc */
  id: number;
  title: string;
  description?: string;
}

export type BookApiSpec = Tspec.DefineApiSpec<{
  paths: {
    '/books/{id}': {
      get: {
        summary: 'Get book by id',
        path: { id: number },
        responses: { 200: Book },
      },
    },
  }
}>;

Run the following command to generate OpenAPI Spec:

npx tspec generate --outputPath openapi.json

(For readability, the generated OpenAPI Spec is formatted with yaml)

openapi: 3.0.3
info:
  title: Tspec API
  version: 0.0.1
paths:
  /books/{id}:
    get:
      operationId: BookApiSpec_get_/books/{id}
      tags:
        - Book
      summary: Get book by id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      description: Schema description defined by JSDoc
      type: object
      properties:
        id:
          description: Field description defined by JSDoc
          type: number
        title:
          type: string
        description:
          type: string
      required:
        - id
        - title

If you want to serve Swagger UI, run the following command:

npx tspec server --port 3000

Then, you can access Swagger UI at http://localhost:3000

And you can see schema definitions in the Schemas tab.

Express Integration

Tspec automatically parses your Express handler type to generate parameters(path, query, body) and responses schemas. And you can use TspecDocsMiddleware to serve Swagger UI.

import { Tspec, TspecDocsMiddleware } from "tspec";
import express, { Request, Response } from "express";

const getBookById = (
  req: Request<{ id: string }>, res: Response<Book>,
) => {
  res.json({
    id: +req.params.id,
    title: 'Book Title',
    description: 'Book Description',
  });
}

export type BookApiSpec = Tspec.DefineApiSpec<{
  tags: ['Book'],
  paths: {
    '/books/{id}': {
      get: {
        summary: 'Get book by id',
        handler: typeof getBookById
      },
    },
  }
}>;

const initServer = async () => {
  const app = express()
  app.get('/books/:id', getBookById);
  app.use('/docs', await TspecDocsMiddleware());
  app.listen(3000);
}
initServer();

NestJS Support

Tspec can generate OpenAPI spec directly from your NestJS controllers:

@Controller('books')
export class BooksController {
  @Get(':id')
  findOne(@Param('id') id: string): Promise<Book> {
    // ...
  }

  @Post()
  create(@Body() dto: CreateBookDto): Promise<Book> {
    // ...
  }
}

npx tspec generate --nestjs

See the NestJS Integration Guide for more details.

Documentation

https://ts-spec.github.io/tspec

Stargazers over time

Give a ⭐️ if you find this project useful and to show your appreciation!