express-endpoints-collection

Description

This package provides easy to use helper for creating API endpoints in Express with TypeScript inference, validation and OpenAPI 3 schema out of the box.

No need to duplicate OpenAPI definitions in your codebase. Just define your API endpoints and automatically generate OpenAPI 3 schema.

You can configure exposed endpoints, request and response schemas, and validation rules.

Features

• Fully typed endpoints (TypeScript hints and checks)
  • Request body
  • Response body
  • Query parameters
  • Path parameters
  • Headers
• Automatic OpenAPI 3 schema generation
• Request and response validation using Zod
• Middleware support
• Minimal setup

Installation

1npm install express-endpoints-collection
2
3# or
4
5yarn add express-endpoints-collection
6
7# or
8
9pnpm add express-endpoints-collection

Usage

1import express, { Express } from "express";
2import bodyParser from "body-parser";
3import { z } from "zod";
4import { EndpointsCollection } from "express-endpoints-collection";
5import { generateOpenAPI } from "express-endpoints-collection/generator";
6
7// 1. Create express app
8const app: Express = express();
9app.use(bodyParser.json());
10
11// 2. Create endpoints collection, this will store all your endpoints
12const endpointsCollection = new EndpointsCollection();
13
14// 3. Add new endpoint
15endpointsCollection.post(
16  "/add",
17  {
18    inputSchema: {
19      body: z.object({
20        a: z.number(),
21        b: z.number(),
22      }),
23    },
24    outputSchema: [
25      {
26        status: 200,
27        body: z.object({
28          result: z.number(),
29        }),
30      },
31    ],
32    summary: "Add two numbers",
33  },
34  // 4. req and res are fully typed!
35  (req, res) => {
36    const { a, b } = req.body;
37    res.json({ result: a + b });
38  },
39);
40
41// 5. Collection creates its own router, to use it just add it to your app
42app.use(endpointsCollection.getRouter());
43
44// 6. Expose OpenAPI 3 schema
45app.get("/openapi", (req, res) => {
46  res.setHeader("Content-Type", "text/yaml");
47  res.send(
48    generateOpenAPI({
49      title: "Minimal demo",
50      version: "1.0.0",
51      endpoints: endpointsCollection.getEndpoints(),
52      servers: ["http://localhost:3000"],
53    }),
54  );
55});
56
57// 7. Start the server and done!
58app.listen(3000, () => {
59  console.info(`Server is running on port http://localhost:3000`);
60});

it will generate OpenAPI 3 definition as follow:

1openapi: 3.0.0
2info:
3  title: Minimal demo
4  version: 1.0.0
5components:
6  schemas: {}
7  parameters: {}
8paths:
9  /add:
10    post:
11      summary: Add two numbers
12      requestBody:
13        content:
14          application/json:
15            schema:
16              type: object
17              properties:
18                a:
19                  type: number
20                b:
21                  type: number
22              required:
23                - a
24                - b
25      responses:
26        "200":
27          description: Response for status code 200
28          content:
29            application/json:
30              schema:
31                type: object
32                properties:
33                  result:
34                    type: number
35                required:
36                  - result

or as JSON

1{
2  "openapi": "3.0.0",
3  "info": {
4    "title": "Minimal demo",
5    "version": "1.0.0"
6  },
7  "components": {
8    "schemas": {},
9    "parameters": {}
10  },
11  "paths": {
12    "/add": {
13      "post": {
14        "summary": "Add two numbers",
15        "requestBody": {
16          "content": {
17            "application/json": {
18              "schema": {
19                "type": "object",
20                "properties": {
21                  "a": {
22                    "type": "number"
23                  },
24                  "b": {
25                    "type": "number"
26                  }
27                },
28                "required": ["a", "b"]
29              }
30            }
31          }
32        },
33        "responses": {
34          "200": {
35            "description": "Response for status code 200",
36            "content": {
37              "application/json": {
38                "schema": {
39                  "type": "object",
40                  "properties": {
41                    "result": {
42                      "type": "number"
43                    }
44                  },
45                  "required": ["result"]
46                }
47              }
48            }
49          }
50        }
51      }
52    }
53  }
54}

Example

Type inference and checks:

License

MIT