search

Cody2333 / koa-swagger-decorator

using decorator to automatically generate swagger doc for koa-router
348 stars 81 forks source link

too specific #181

Open mbsanchez01 opened 11 months ago

mbsanchez01 commented 11 months ago

This npm package is a perfect starting point for the Open API generation on Koa projects. But it's very specific, you are forcing people to use the controller as a class and to use your swagger router as an entry point.

What happens if I just want to user the Koa Router like this:

import Router from 'koa-router';
import { Context, Next } from 'koa';

const publicUserRouter = new Router({});

publicUserRouter.get('/users', (ctx: Context, next: Next) => {
   console.log('logic to get the users');
   ctx.body = {};
   return next();
});

It would be great if we could annotate that definition in some way. Moreover, I think this package does not detect headers and query parameters automatically from the code. Also, you don't give the user the possibility to name the types, you are given names using the class name, and the method name, which IMHO is awful. What if the user wants to reuse the type for other endpoint inputs/outputs?

Maybe you should find a more generic approach like swagger-autogen, the only drawback is that swagger-autogen does not support zod as input types. That is why I was looking for other alternatives without luck until now.

I congrats you for you efforts, but i know it could be better. Thank you in advance.

Cody2333 commented 11 months ago

  1. SwaggerRouter extends the koa-router class, so you can simply using SwaggerRouter as a replacement of koa-router.

    import { SwaggerRouter } from 'koa-swagger-decorator';
const router = new SwaggerRouter({});
router.get('/xxx', (ctx, next) => {...}

  2. i would try to add support for customizing schema names soon. You can simply resue your defined zod schemas in your code