upd: egg-swagger-doc

Author: csxiaoyaojianxian

17-nodejs/20-egg-swagger-doc/app/contract/format.js

@@ -0,0 +1,12 @@
+const JsonBody = {
+  code: { type: 'number', required: true, example: 0 },
+  message: { type: 'string', required: true, example: 'success' },
+  data: { type: 'Enum', required: true, example: [] },
+}
+
+module.exports = {
+  indexJsonBody: {
+    ...JsonBody,
+    data: { type: 'string', example: 'test' },
+  },
+};

17-nodejs/20-egg-swagger-doc/app/controller/home.js

@@ -0,0 +1,27 @@
+const Controller = require('egg').Controller;
+
+/**
+ * @controller HomeController
+ */
+class HomeController extends Controller {
+  /**
+   * @router get /index  路径
+   * @summary 接口的小标题信息
+   * @description 接口的描述信息
+   * @request query integer id 对参数id的描述
+   * @request query string name 对参数name的描述
+   * @response 200 indexJsonBody
+   */
+  async index () {
+    console.log(111, this.ctx.query)
+    this.ctx.body = {
+      code: 0,
+      message: '',
+      data: {
+        result: this.ctx.query.name || 'none'
+      }
+    }
+  }
+}
+
+module.exports = HomeController;

17-nodejs/20-egg-swagger-doc/app/router.js

@@ -0,0 +1,5 @@
+module.exports = app => {
+  const { router, controller } = app;
+
+  router.get('/index', controller.home.index);
+};

17-nodejs/20-egg-swagger-doc/config/config.default.js

@@ -0,0 +1,28 @@
+exports.keys = 'csxiaoyao';
+
+// egg-swagger-doc 配置信息
+exports.swaggerdoc = {
+  dirScanner: './app/controller', // 配置自动扫描的控制器路径
+  apiInfo: {
+    title: '接口文档', // 接口文档的标题
+    description: 'swagger 测试接口文档', // 接口文档描述
+    version: '1.0.0', // 接口文档版本
+    termsOfService: 'http://swagger.io/terms/', // 服务条件
+    contact: {
+      email: 'sunjianfeng@csxiaoyao.com' // 联系方式
+    },
+    license: {
+      name: 'Apache 2.0',
+      url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+    },
+  },
+  basePath: '/', // 配置基础路径
+  schemes: ['http', 'https'], // 配置支持的协议
+  consumes: ['application/json'], // 指定处理请求的提交内容类型 (Content-Type)，如 application/json、text/html
+  produces: ['application/json'], // 指定返回的内容类型，仅当 request 请求头中的(Accept)类型中包含该指定类型才返回
+  securityDefinitions: {}, // 配置接口安全授权方式
+  enableSecurity: false, // 是否启用授权，默认 false
+  // enableValidate: true, // 是否启用参数校验，默认 true
+  routerMap: false, // 是否启用自动生成路由(实验功能)，默认 true
+  enable: true   // 默认 true
+}

17-nodejs/20-egg-swagger-doc/config/plugin.js

@@ -0,0 +1,5 @@
+// 配置 egg-swagger-doc 插件信息。
+exports.swaggerdoc = {
+  enable: true,   // 是否启用。
+  package: 'egg-swagger-doc', // 指定包名称。
+};

17-nodejs/20-egg-swagger-doc/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "egg-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "egg-bin dev"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "egg": "^2.29.4",
+    "egg-swagger-doc": "^2.3.2",
+    "koa2-swagger-ui": "^5.1.0",
+    "swagger-jsdoc": "*"
+  },
+  "devDependencies": {
+    "egg-bin": "^4.16.2"
+  }
+}