egg生成swagger文档并同步到yapi一、egg生成swagger文档 1.1 安装egg-swagger-doc

一、egg生成swagger文档

1.1 安装egg-swagger-doc插件

npm i egg-swagger-doc --save

1.2 修改config/plugin.js

增加下面代码

swaggerdoc: {
    enable: true,
    package: 'egg-swagger-doc',
  },

1.3 修改config/config.default.js

增加swagger相关的配置

/**
   * 配置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,
 
  }

1.4 根据文件添加具体模块

// app/controller/test.js
/**
 *  笔记路由note
 * @Controller 笔记
 */

1.5 编写接口的相关注释

// app/controller/test.js
  /**
   * @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 test(){
        xxxxxx
  }

1.6 新建contract文件夹，新建index.js

//app/contract/index.js

1.7 验证访问

访问api的界面展示：http://localhost:7001/swagger-ui.html
获取swagger的json文件：http://localhost:7001/swagger-doc

二、同步swagger文档到yapi中

2.1 编写脚本将生成的swagger的json文件保存到本地

//create_swagger.js
'use strict';
const http = require('http');
const fs = require('fs');
// URL地址
const url = 'http://localhost:7001/swagger-doc'; // 替换为要获取的URL地址
// 创建写入流对象
const writeStream = fs.createWriteStream('swagger.json');
// 发起GET请求
http.get(url, response => {
    // 通过管道将数据从服务器传输到文件
    response.pipe(writeStream);
});
console.log(`正在获取 ${url}...`);

2.2 安装导入yapi的插件

参考链接：hellosean1025.github.io/yapi/docume…

使用方法

第一步，确保 yapi-cli >= 1.2.7 版本，如果低于此版本请升级 yapi-cli 工具

npm install -g yapi-cli

第二步，在任意一个目录下新建配置文件 yapi-import.json，内容如下：

{
  "type": "swagger",
  "token": "17fba0027f300248b804",
  "file": "swagger.json",
  "merge": "normal",
  "server": "http://yapi.local.qunar.com:3000"
}

type 是数据数据方式，目前官方只支持 swagger token 是项目 token，在 项目设置 -> token 设置获取 file 是 swagger 接口文档文件，可使用绝对路径或 url merge 有三种导入方式(v1.3.23+支持) normal, good, mergin

普通模式(normal)：不导入已存在的接口；
智能合并(good)：已存在的接口，将合并返回数据的 response，适用于导入了 swagger 数据，保留对数据结构的改动；
完全覆盖(mergin)：不保留旧数据，完全使用新数据，适用于接口定义完全交给后端定义，默认为 normal server 是 yapi 服务器地址第三步，在新建配置文件的当前目录，执行下面指令

yapi import

egg生成swagger文档并同步到yapi