koa-router-zod-swagger

Validate router input and host swagger ui based on @koa/router and zod schema

Installation

1$ npm install koa-router-zod-swagger
2
3$ yarn add koa-router-zod-swagger
4
5$ pnpm install koa-router-zod-swagger

Uses Zod, @koa/router And koa2-swagger-ui

Usage

Import Packages

1import Koa from 'koa';
2import KoaRouter from 'koa-router';
3import { z } from 'zod';
4import { ZodValidator, ZodValidatorProps, KoaRouterSwagger } from 'koa-router-zod-swagger';
5const app = new Koa();
6const router = new KoaRouter();

Create validation Zod object schema (See Zod Documentation)

1const RouterSchema: ZodValidatorProps = {
2  summary: 'Make test post request',
3  description: `Make [API](https://en.wikipedia.org/wiki/API) Request`,
4  query: z.object({
5    queryParam: z.string(),
6  }),
7  body: z.object({
8    bodyParamString: z.string(),
9    bodyParamNumber: z.number(),
10  }),
11  files: {
12    file1: true,
13    multipleFiles: {
14      multiple: true
15    },
16    optionalFile: {
17      optional: true
18    }
19  },
20  filesValidator: z.object({
21    file1: z.object({ // formidable.File object
22      size: z.number().min(5 * 1000).max(7 * 1000), // Min 5KB, Max 7KB.
23      mimetype: z.enum(['image/png'])
24    })
25  }),
26  params: z.object({
27    param1: z.string(),
28  }),
29  header: z.object({
30    'user-agent': z.string()
31  }),
32  response: {
33    description: 'Response returned successfully',
34    validate: true,
35    body: z.object({
36      query: z.object(),
37      params: z.object(),
38      body: z.object()
39    })
40  }
41};

Validate

1router.post('/api/:param1', ZodValidator(RouterSchema), (ctx) => {
2  ctx.body = {
3    query: ctx.request.query,
4    params: ctx.params,
5    body: ctx.request.body,
6  };
7});

Serve Swagger Docs (pass koa2-swagger-ui config as uiConfig)

1router.get(
2  '/docs',
3  KoaRouterSwagger(router, {
4    routePrefix: false,
5    title: 'Test Api',
6    swaggerOptions: {
7      spec: {
8        info: {
9          version: '1.0.0',
10          description: 'This is test api specs',
11        },
12      },
13    },
14  }),
15);