tspec v0.1.112
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
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();
Documentation
https://ts-spec.github.io/tspec
Stargazers over time
Give a ⭐️ if you find this project useful and to show your appreciation!
4 months ago
4 months ago
6 months ago
7 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
9 months ago
9 months ago
8 months ago
11 months ago
11 months ago
9 months ago
10 months ago
11 months ago
11 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago