swagger-typed-express-docs

swagger-typed-express-docs keep you simple document your endpoints with just one single source of truth which

this project generates OpenAPI 3.0.0, not swagger!

• Generate OpenAPI API documentation
• Compile time validations - Infer Typescript static types out of the box
• Runtime validate each of your HTTP request with user-friendly error messages

To do that there is just a simple high-order-function API. So you can just simply wrap your endpoint with the apiDoc(...) and initialize project via initApiDocs()

Example usage

You can see full app example in the repository:

1import express from 'express'
2import { apiDoc, initApiDocs, T } from 'swagger-typed-express-docs'
3import swaggerUi from 'swagger-ui-express'
4
5const app = express()
6const port = 3000
7
8app.get(
9  '/user/:userId',
10  /**
11   * adding metadata for handlers where we want to have
12   *  - runtime checks
13   * - compile-time checks
14   * - generate swagger documentation
15   */
16  apiDoc({
17    params: {
18      userId: T.string,
19    },
20    query: {
21      name: T.string,
22      header: T.list(T.enum(['a', 'b', 'c'] as const)),
23    },
24    body: {
25      header: T.list(T.enum(['a', 'b', 'c'] as const)),
26      message: T.string,
27      footer: T.string,
28    },
29    returns: T.object({
30      enhancedBody: T.object({
31        data: T.enum(['a', 'b', 'c'] as const),
32      }),
33    }),
34  })((req, res) => {
35    const body = req.body
36    const query = req.query
37
38    // res.send is typed by typescript, but it do not transform values by tSchema, so
39    // you may use tSend instead
40    res.tSend({
41      body,
42      query,
43    })
44  })
45)
46/**
47 * before you start the server you have to setup library
48 */
49const swaggerJSON = initApiDocs(app, { info: { title: 'my application' } })
50
51app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerJSON))

Package API

The whole library expose 2 main functions: initApiDocs(...) and & apiDoc(...)

initApiDocs

This method takes a swagger metadata which will be deeply merged into generated documentation.

initApiDocs() returns generated Swagger JSON which you can use to document your API.

example usage

1const swaggerJSON = initApiDocs(app, { info: { title: 'my application' } })

to make the application work you have to call initApiDocs() at the end of routes definition and before you start app.listen(...)

apiDoc

apiDoc(...) is high-order-function which you use to wrap express endpoint handler and define a meta-information about inputs & outputs of each API handler.

example usage:

1import { T } from 'swagger-typed-express-docs'
2
3app.get(
4  '/',
5  apiDoc({
6    query: {
7      name: T.string
8      header: T.list(T.enum(['a', 'b', 'c'] as const))),
9    },
10    body: {
11      header: T.list(T.enum(['a', 'b', 'c'] as const))),
12      message: T.null_list,
13      footer: T.string,
14    },
15    returns: T.null_object({
16      data: T.null_object({
17        nestedData: T.enum(['a', 'b', 'c'] as const),
18      }),
19    }),
20  })((req, res) => {
21    const body = req.body
22    const query = req.query
23
24    res.send({
25      body,
26      query,
27    })
28  })
29)

The library exposes many functions and objects which help you to create schema as you want.

• T.string(...)
• T.null_string(...)
• T.boolean(...)
• T.null_boolean(...)
• T.number(...)
• T.null_number(...)
• T.enum(...)
• T.null_enum(...)
• T.oneOf(...)
• T.null_oneOf(...)
• T.any(...)
• T.null_any(...)
• T.object(...)
• T.null_object(...)
• T.list(...)
• T.null_list(...)
• T.nonNullable(...)

if you want to see more examples on how to build schema structure by function compositions you can check the tests

Setup environments

Express body parsing

if you want to parser body, you have to setup body parser express middleware.

1app.use(express.json())

Typescripts null checks

to make fully work tNonNullable you have to setup tsconfig.json properly.

1{
2  ...
3  "compilerOptions": {
4    ...
5    "strictNullChecks": true,
6  }
7}

Example library preview

Decisions

if some field in the object is nullable null_ key may not be required, but in TS types, only value is of type | undefined

so the non existed keys are nullable as well, thanks to this, the schema is simplier for the writter, because there is less edge cases to think about

All defined schema attribute stripping

if you define one of apiDoc objects like query, body, params or headers it'll strip all unknown object attributes so omit potential security data injections

By default, if you do not define some of the tSchema, nothing is validate or parsed for current object

Express query parsing

You can parse query thanks to express-query-parser library.

We parser to keep parsing only undefined and null values and the rest may be done by transform types. Many transform types is predefined in the T.cast. object.

1import { queryParser } from 'express-query-parser'
2
3app.use(
4  queryParser({
5    parseNumber: false,
6    parseBoolean: false,
7    // turn on only null & undefined values, to use T.cast. utils
8    parseNull: true,
9    parseUndefined: true,
10  })
11)
12
13app.get(
14  '/',
15  apiDoc({
16    query: {
17      name: T.cast.number,
18      ids: T.extra.null_toListIfNot(T.cast.number),
19    },
20  })((req, res) => {
21    const body = req.body
22    const query = req.query
23
24    res.send({
25      body,
26      query,
27    })
28  })
29)

if you want to parse string 'null' by yourself, you need to create a custom T.transform data type which will handle this edge case

Validating output via res.tSend

The library automatically injects the tSend function into res.tSend. This function takes data and sends a 200 success status response. However, before sending, it verifies if the schema matches the apiDoc({ returns: ... }) schema definition and sanitizes the data. Therefore, if you send more data than what is defined (for example, an object with additional attributes), the surplus data will be stripped. This mechanism enhances the function's reliability.

After defining T.transform types, encoders are applied, and the data is transformed accordingly.

Custom transformation of incoming data (Encoders / decoders)

Data Transformation Flow: User -> HTTP -> Encoded -> Decoded -> Express Handler Express Handler -> Decoded -> Encoded -> HTTP -> User

• Users interact exclusively with encoded types.
• Express handlers interact solely with decoded types.

Null Handling:

• If a data type is nullable, null and undefined values are automatically handled, and the encoder/decoder functions will not be invoked.
• If null is not explicitly defined, encoder and decoder functions may still be called with null or undefined values. In such cases, handling must be implemented manually within the parser/serializer functions.

Data utils:

- T.deepNullable

Vocabularies

decoder = parser encoder = serializer transform = encoder + decoder

TODO:

• remove async validations
• do porting to zod
• make smarter union object matching