features:add swagger jsdoc support

example/08-swagger/index.ts

@@ -1,32 +1,56 @@
-import {
-  controller,
-  DarukContext,
-  DarukServer,
-  get,
-  Next,
-  request,
-  responses,
-  summary
-} from '../../src';
+import { controller, DarukContext, DarukServer, get, Next } from '../../src';
+import { join } from 'path';
 
 @controller()
 class HelloWorld {
-  @request('get', '/')
-  @summary('daruk controller helloworld')
-  @responses({
-    200: { description: 'hello world' }
-  })
+  // https://github.com/Surnet/swagger-jsdoc/tree/v6/docs
+  // https://swagger.io/docs/specification/describing-parameters/
+  /**
+   * @openapi
+   * /:
+   *  get:
+   *   summary: Index page
+   *   description: Welcome to swagger-jsdoc!
+   *   tags:
+   *     - WebPage
+   *   parameters:
+   *     - name: username
+   *       in: query
+   *       description: username
+   *       required: false
+   *       default: nobody
+   *       schema:
+   *         type: string
+   *   responses:
+   *    200:
+   *      description: Returns hello world string;
+   *      content:
+   *       text/plain:
+   *        schema:
+   *         type: string
+   *         example: hello world nobody
+   */
   @get('/')
-  public static async index(ctx: DarukContext, next: Next) {
-    ctx.body = 'hello world';
+  public async index(ctx: DarukContext, next: Next) {
+    let username = ctx.query.username || 'nobody';
+    ctx.body = `hello world ${username}`;
   }
 }
 
 (async () => {
+  let port = 3000;
   let app = DarukServer({
-    routerType: 'swagger'
+    swagger: {
+      prefix: '/swagger',
+      title: 'swagger demo',
+      description: 'swagger daruk example',
+      version: '1.0.1',
+      enable: true,
+      host: `localhost:${port}`,
+      basePath: '/',
+      apis: [join(__dirname, './index.ts')]
+    }
   });
-  let port = 3000;
   await app.binding();
   app.listen(port);
   app.logger.info(`app listen port ${port}`);

package.json

@@ -80,8 +80,8 @@
     "@koa/router": "^9.4.0",
     "@types/cron": "^1.7.1",
     "@types/koa": "^2.0.46",
-    "@types/koa__router": "^8.0.2",
     "@types/koa-cookie": "^1.0.0",
+    "@types/koa__router": "^8.0.2",
     "@types/recursive-readdir": "^2.2.0",
     "@types/url-join": "^4.0.0",
     "chalk": "^2.4.1",
@@ -101,10 +101,11 @@
     "koa-body": "^4.1.0",
     "koa-cookie": "^1.0.0",
     "koa-onerror": "^4.1.0",
-    "koa-swagger-decorator": "1.7.4",
+    "koa2-swagger-ui": "^5.10.0",
     "object-assign-deep": "^0.4.0",
     "recursive-readdir": "^2.2.2",
     "reflect-metadata": "^0.1.13",
+    "swagger-jsdoc": "^6.2.8",
     "url-join": "^4.0.0"
   },
   "nyc": {

src/core/daruk_default_options.ts

@@ -10,11 +10,10 @@ export default function getDefaultOptions(
   debug = true
 ): Options {
   return {
-    routerType: 'koa-router',
     name,
     exitHook: true,
     routerOptions: {},
-    swaggerOptions: { title: 'Daruk Server', description: 'Daruk API DOC', version: '1.0.0' },
+    swagger: {},
     rootPath,
     middlewareOrder: [],
     bodyOptions: {},

src/decorators/index.ts

@@ -5,32 +5,5 @@ export * from './response';
 export * from './controller';
 export * from './request';
 export * from './middlewares';
-export {
-  request,
-  tags,
-  query,
-  path,
-  body,
-  formData,
-  middlewares as swaggerMiddlewares,
-  security,
-  summary,
-  description,
-  desc,
-  responses,
-  deprecated,
-  tagsAll,
-  responsesAll,
-  middlewaresAll,
-  securityAll,
-  deprecatedAll,
-  queryAll,
-  swaggerClass,
-  swaggerProperty,
-  prefix as swaggerPrefix,
-  header as swaggerHeader,
-  PropertyOptions,
-  PropertyType
-} from 'koa-swagger-decorator';
 // export validate
 export { validate } from 'daruk-validate';

src/plugins/router.ts

@@ -4,11 +4,12 @@
  * @fileoverview 重构router部分,使用依赖控制controller
  */
 import Router = require('@koa/router');
+import swaggerJsdoc from 'swagger-jsdoc';
 import assert = require('assert');
 import { Container } from 'inversify';
 import is = require('is');
 import Koa = require('koa');
-import { SwaggerRouter } from 'koa-swagger-decorator';
+import { koaSwagger } from 'koa2-swagger-ui';
 import urljoin = require('url-join');
 import Daruk from '../core/daruk';
 import { darukContainer } from '../core/inversify.config';
@@ -49,13 +50,9 @@ class RouterController implements PluginClass {
   public async initPlugin(daruk: Daruk) {
     daruk.on('init', () => {
       daruk.emit('routerUseBefore');
+      const options = daruk.options;
 
-      if (daruk.options.routerType === 'swagger') {
-        daruk.router = new SwaggerRouter(daruk.options.routerOptions, daruk.options.swaggerOptions);
-        daruk.router.swagger();
-      } else {
-        daruk.router = new Router(daruk.options.routerOptions);
-      }
+      daruk.router = new Router(options.routerOptions);
 
       const controllers = Reflect.getMetadata(CONTROLLER_CLASS, Reflect) || [];
       const Services = Reflect.getMetadata(SERVICE, Reflect) || [];
@@ -67,10 +64,6 @@ class RouterController implements PluginClass {
           return Apriority - Bpriority;
         })
         .forEach((controller: Constructor) => {
-          if (daruk.options.routerType === 'swagger') {
-            console.log(controller);
-            daruk.router.map(controller, { doValidation: true });
-          }
           // 获取是否整个类被disabled
           const classDisabled =
             Reflect.getMetadata(CONTROLLER_DISABLED_CLASS, controller) === 'disabled';
@@ -136,6 +129,29 @@ class RouterController implements PluginClass {
           });
         });
 
+      const swagger = options.swagger;
+      if (swagger.enable) {
+        const swaggerOptions = {
+          definition: {
+            openapi: '3.0.0',
+            info: {
+              title: swagger.title || 'daruk swagger docs',
+              description: swagger.description || 'a sample api',
+              version: swagger.version || '1.0.0'
+            },
+            host: swagger.host,
+            basePath: swagger.basePath
+          },
+          apis: swagger.apis
+        };
+        if (swagger.host) swaggerOptions.definition.host = swagger.host;
+        if (swagger.basePath) swaggerOptions.definition.basePath = swagger.basePath;
+        const openapiSpecification = swaggerJsdoc(swaggerOptions);
+        daruk.router.get(
+          swagger.prefix,
+          koaSwagger({ routePrefix: false, swaggerOptions: { spec: openapiSpecification } })
+        );
+      }
       // @ts-ignore
       daruk.app.use(daruk.router.routes(), 'router');
       // @ts-ignore

src/typings/daruk_options.d.ts

@@ -18,13 +18,17 @@ interface ErrorOptions {
   redirect?: (err: Error, ctx: DarukContext) => void;
 }
 
+
+
+
 export interface Options {
   middlewareOrder: string[];
   name: string;
   rootPath: string;
   debug: boolean;
   bodyOptions: koaBody.IKoaBodyOptions;
   exitHook: boolean;
+
   // monitor: {
   //   enable: boolean;
   //   v8AnalyticsPath: string;

types/decorators/index.d.ts

@@ -5,5 +5,4 @@ export * from './response';
 export * from './controller';
 export * from './request';
 export * from './middlewares';
-export { request, tags, query, path, body, formData, middlewares as swaggerMiddlewares, security, summary, description, desc, responses, deprecated, tagsAll, responsesAll, middlewaresAll, securityAll, deprecatedAll, queryAll, swaggerClass, swaggerProperty, prefix as swaggerPrefix, header as swaggerHeader, PropertyOptions, PropertyType } from 'koa-swagger-decorator';
 export { validate } from 'daruk-validate';

types/typings/daruk_options.d.ts

@@ -18,13 +18,17 @@ interface ErrorOptions {
   redirect?: (err: Error, ctx: DarukContext) => void;
 }
 
+
+
+
 export interface Options {
   middlewareOrder: string[];
   name: string;
   rootPath: string;
   debug: boolean;
   bodyOptions: koaBody.IKoaBodyOptions;
   exitHook: boolean;
+
   // monitor: {
   //   enable: boolean;
   //   v8AnalyticsPath: string;