前言：
后端java或者其他语言引入swagger是可以的，当然我们的egg中也是支持引入的，需要引入 egg-swagger-doc 。
实现效果：
官方：入口
实现步骤：
1、安装
cnpm i egg-swagger-doc --save
2、打开 config/plugin.js ，加入下面内容
exports.swaggerdoc = {
enable: true,
package: 'egg-swagger-doc',
};
3、打开 config/config.default.js
const config = exports = {};
/**
* 配置swagger
* @property {String} dirScanner - 插件扫描的文档路径
* @property {String} basePath - api前置路由
* @property {Object} apiInfo - 可参考Swagger文档中的Info
* @property {Array[String]} apiInfo - 可参考Swagger文档中的Info
* @property {Array[String]} schemes - 访问地址协议http或者https
* @property {Array[String]} consumes - contentType的集合
* @property {Array[String]} produces - contentType的集合
* @property {Object} securityDefinitions - 安全验证，具体参考swagger官方文档
* @property {Boolean} enableSecurity - 是否使用安全验证
* @property {Boolean} routeMap - 是否自动生成route
* @property {Boolean} enable - swagger-ui是否可以访问
*/
config.swaggerdoc = {
dirScanner: './app/controller',
apiInfo: {
title: 'egg-swagger',
description: 'swagger-ui for egg',
version: '1.0.0',
},
schemes: ['http'],
// consumes: ['application/json'],
// produces: ['application/json'],
securityDefinitions: {
// apikey: {
// type: 'apiKey',
// name: 'clientkey',
// in: 'header',
// },
// oauth2: {
// type: 'oauth2',
// tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
// flow: 'password',
// scopes: {
// 'write:access_token': 'write access_token',
// 'read:access_token': 'read access_token',
// },
// },
},
// enableSecurity: false,
// enableValidate: true,
routerMap: true,
enable: true,
}
到这一步，配置文件已经到位了，现在得加入具体的路由注释了
4、添加模块
/**
* 笔记路由note
* @Controller 笔记
*/
5、添加具体方法注释，get请求
/**
* @summary 获取笔记
* @description 获取笔记
* @Router get /setNoteList
* @request query string username 账户名
* @request query integer page 页码 默认 1
* @request query integer pageSize 单页数量 默认 10
* @Request header string authorization token值
* */
async getNoteList(){
}
注释含义：
- @controller 这个便变成一个tag
- @summary 简介
- @description 描述
- @router 就是请求地址
- @request 其实是swagger里面的parames，其中的authorize_login是定义中app/contract的一个object。翻译到swagger就是一个 object的引用。
- @response 响应，其中的baseResponse，同上。
- @consumes 提交到请求的数据格式(即带body的请求，例如post，有效其他无效），如果没有定义，则跟从配置文件设置。如果要多种选择，可以用空格分开，例如 @consumes html/text application/json。
- @product 同上。
6、post请求，注意，这里的参数body后面的 postNoteParams 是需要在contract中定义方法
/**
* @summary 新增笔记
* @description 新增笔记
* @Router post /setNoteList
* @request body postNoteParams *body
* @Request header string authorization token值
*/
async postNoteList(){
}
7、新建contract文件夹，新建index.js
index.js内容
module.exports = {
//账户
postAccountParams: {
username: { type: 'string', required: false, description: '账户名' },
password: { type: 'string', required: false, description: '密码' },
role: { type: 'string', required: false, description: '权限' },
phone: { type: 'string', required: false, format: /^1[34578]\d{9}$/, description: '电话' },
},
}
8、将默认地址指向 swagger的地址，打开路由文件，如果不指向，地址是：http://localhost:7001/swagger-ui.html
/**
* 路由配置
* @param app
*/
module.exports = app => {
const { router, controller, middleware } = app;
//默认打开swagger
router.redirect('/', '/swagger-ui.html',302);
}
9、打开页面，输入ip+端口号看效果，http://localhost:7001
