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.

Installation

1npm install tspec

Usage

1import { Tspec } from "tspec";
2
3/** Schema description defined by JSDoc */
4interface Book {
5  /** Field description defined by JSDoc */
6  id: number;
7  title: string;
8  description?: string;
9}
10
11export type BookApiSpec = Tspec.DefineApiSpec<{
12  paths: {
13    '/books/{id}': {
14      get: {
15        summary: 'Get book by id',
16        path: { id: number },
17        responses: { 200: Book },
18      },
19    },
20  }
21}>;

Run the following command to generate OpenAPI Spec:

1npx tspec generate --outputPath openapi.json

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

1openapi: 3.0.3
2info:
3  title: Tspec API
4  version: 0.0.1
5paths:
6  /books/{id}:
7    get:
8      operationId: BookApiSpec_get_/books/{id}
9      tags:
10        - Book
11      summary: Get book by id
12      parameters:
13        - name: id
14          in: path
15          required: true
16          schema:
17            type: number
18      responses:
19        '200':
20          description: OK
21          content:
22            application/json:
23              schema:
24                $ref: '#/components/schemas/Book'
25components:
26  schemas:
27    Book:
28      description: Schema description defined by JSDoc
29      type: object
30      properties:
31        id:
32          description: Field description defined by JSDoc
33          type: number
34        title:
35          type: string
36        description:
37          type: string
38      required:
39        - id
40        - title

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

1npx 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.

1import { Tspec, TspecDocsMiddleware } from "tspec";
2import express, { Request, Response } from "express";
3
4const getBookById = (
5  req: Request<{ id: string }>, res: Response<Book>,
6) => {
7  res.json({
8    id: +req.params.id,
9    title: 'Book Title',
10    description: 'Book Description',
11  });
12}
13
14export type BookApiSpec = Tspec.DefineApiSpec<{
15  tags: ['Book'],
16  paths: {
17    '/books/{id}': {
18      get: {
19        summary: 'Get book by id',
20        handler: typeof getBookById
21      },
22    },
23  }
24}>;
25
26const initServer = async () => {
27  const app = express()
28  app.get('/books/:id', getBookById);
29  app.use('/docs', await TspecDocsMiddleware());
30  app.listen(3000);
31}
32initServer();

Documentation

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

---

Stargazers over time

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