vaso991 / koa-router-zod-swagger

Koa2 validator and swagger generator.

koa-router-zod-swagger

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

Installation

$ npm install koa-router-zod-swagger

$ yarn add koa-router-zod-swagger

$ pnpm install koa-router-zod-swagger

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

Usage

Import Packages

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

Create validation Zod object schema (See Zod Documentation)

const RouterSchema: ZodValidatorProps = {
  summary: 'Make test post request',
  description: `Make [API](https://en.wikipedia.org/wiki/API) Request`,
  query: z.object({
    queryParam: z.string(),
  }),
  body: z.object({
    bodyParamString: z.string(),
    bodyParamNumber: z.number(),
  }),
  files: {
    file1: true,
    multipleFiles: {
      multiple: true
    },
    optionalFile: {
      optional: true
    }
  },
  filesValidator: z.object({
    file1: z.object({ // formidable.File object
      size: z.number().min(5 * 1000).max(7 * 1000), // Min 5KB, Max 7KB.
      mimetype: z.enum(['image/png'])
    })
  }),
  params: z.object({
    param1: z.string(),
  }),
  header: z.object({
    'user-agent': z.string()
  }),
  response: {
    description: 'Response returned successfully',
    validate: true,
    body: z.object({
      query: z.object(),
      params: z.object(),
      body: z.object()
    })
  }
};

Validate

router.post('/api/:param1', ZodValidator(RouterSchema), (ctx) => {
  ctx.body = {
    query: ctx.request.query,
    params: ctx.params,
    body: ctx.request.body,
  };
});

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

router.get(
  '/docs',
  KoaRouterSwagger(router, {
    routePrefix: false,
    title: 'Test Api',
    swaggerOptions: {
      spec: {
        info: {
          version: '1.0.0',
          description: 'This is test api specs',
        },
      },
    },
  }),
);

koa-router-zod-swagger's Issues

ResponseType Body should be optional?

Hey! thanks for the awesome lib. This is really useful.

I'm having an issue where I have to implement empty body responses on my endpoints.

Methods such as DELETE usually return a empty/null body. (Not an empty object)

Basically I just wanna save myself from having to write ctx.body = {} in those cases as I don't think it's necessary and having a hook that adds a empty object to all empty responses can have unaccounted side effects.

Can we make ResponseType .body optional?

ZodValidator not working if when you have other middleware added before ZodValidator

In the current setup if ZodValidator not the first middleware

What I recommend is to modify FindSchemaInStack function to be like this:

function FindSchemaInStack(
  stack: Router.Layer | Router.IMiddleware,
): ZodValidatorProps | undefined {
  if (Object.prototype.hasOwnProperty.call(stack, '_VALIDATOR_PROPS')) {
    // @ts-ignore
    return stack._VALIDATOR_PROPS as ZodValidatorProps;
  }
  if ('stack' in stack) {
    const zodStack = stack.stack.find(stackItem => Object.prototype.hasOwnProperty.call(stackItem, '_VALIDATOR_PROPS'))
    if (zodStack) {
      return FindSchemaInStack(zodStack);
    }
  }
}