eggjs+swagger-ui项目实战（基于Egg企业级框架搭建的服务端+swagger-ui）

Egg框架，一个为企业级框架和应用而生的node.js框架。Egg框架的基本情况我在前一篇文章已经介绍过了，我就不再多赘述。这次我给大家介绍如何搭建一个基于Egg框架的服务端。

创建Egg项目

先新建一个Egg_test文件夹作为项目目录，然后在文件夹中打开命令提示符。

我们直接安装egg的简易框架，这样我们就可以省去很多手工创建目录的流程。安装命令如上图所示。输入命令行：npm init egg --type=simple。然后点击回车确定，等待框架安装完成即可。

我们等框架下载完成后，下一步就是安装项目的依赖文件。输入命令行：npm install。如果各位小伙伴安装过程中有报错，可以使用淘宝的镜像镜像安装（cnpm install）。安装完成后如上图所示。

到了此步。我们一个简单的Egg框架就搭建完成了。我们直接在命令行运行：npm run dev 即可运行项目，我们在浏览器中输入地址http://127.0.0.1:7001便可访问我们创建的项目了，如上图所示。

安装swagger-ui API文档

基本的项目搭建完成后我们开始安装swagger-ui接口文档，安装接口文档方便我们在开发的过程中提高开发的效率，方便调试。

首先我们要按照egg-swagger-doc插件。在命令提示符中输入命令：npm i egg-swagger-doc --save。点击回车等待插件安装完成，如上图所示。

插件安装完成后我们就可以下一步。我们在项目根目录中找到/config/plugin.js文件。我们需要在里面开启egg-swagger-doc插件，我们开启插件。

'use strict';

/** @type Egg.EggPlugin */
module.exports = {
  // had enabled by egg
  // static: {
  //   enable: true,
  // }
  swaggerdoc : {
    enable: true,
    package: 'egg-swagger-doc',
  }
};

开启插件后我们还要在/config/config.default.js文件中对插件进行配置具体配置如下。

// swagger文档配置
  config.swaggerdoc = {
    dirScanner: './app/controller', //插件扫描的文档路径
    apiInfo: {
      title: 'swagger文档',
      description: 'egg swagger-ui接口文档',
      version: '1.0.0',
    },
    consumes: ['application/json','multipart/form-data'], // 指定处理请求的提交内容类型（Content-Type），例如application/json, text/html
    produces: ['application/json','multipart/form-data'], // 指定返回的内容类型，仅当request请求头中的(Accept)类型中包含该指定类型才返回
    schemes: ['http', 'https'],
    routerMap: true, // 是否自动生成route
    enable: true,
  };

测试项目并启动

插件配置完成后我们就可以配置项目路由，将路由重定向到swagger-ui.html。

module.exports = app => {
  const { router, controller } = app;
  //重定向到swagger-ui.html
  router.redirect('/', '/swagger-ui.html', 302);
  
  router.get('/home', controller.home.index);
};

在app目录下新建文件夹 contract（必须）。
在contract目录下新建目录response 和 request 目录。
在response目录下新建base.js。

在base.js中写入一下代码。

'use strict';

module.exports = {
  // 测试模块
  homeResponse: {
    message: { type: 'string' }
  }
};

接下来我们就测试一下，看swagger-ui接口文档是否可以正常运行。

我们直接修改/app/controller/home.js文件。代码如下。

'use strict';

const Controller = require('egg').Controller;
/**
 * @Controller 测试
 */
class HomeController extends Controller {
  /**
  * @summary 接口测试
  * @description 测试swagger文档是否可用
  * @router get /home
  * @request query string str 随机字符串
  * @response 200 homeResponse
  */
  async index() {
    const { ctx } = this;
    const str = ctx.query.str
    ctx.body = {
      message:'swagger 测试正常!!! url传参是:' + str
    };
  }
}

module.exports = HomeController;

保存代码后运行项目：npm run dev 。浏览器打开http://127.0.0.1:7001会重定向到swagger-ui接口文档页面。启动页面如下。