使用Swagger构建Node.js API文档与Mock Server

Swagger是一个编写API文档的套件组合，而不是一个单一的工具。具体可以在官网看到。
Swagger可以实现很多功能，这里只说最基础、常用的：
1. API文档撰写 —— Swagger Editor
2. API文档的显示 —— Swagger UI
3. 生成Mock服务 —— Swagger Editor

目前我们很多项目采用的都是新建一个markdown，写文档，每次改接口，就打开旧的markdown=>编辑=>保存=>复制并发布到项目wiki。

这种方式面临的问题：
1. 撰写方式没有具体的规范，每个后端都有自己的写法，不利于前端理解、项目交接。
2. 由于API文档往往涉及到复杂的参数说明、返回值说明，markdown显示复杂的文档其实并不美观、可读性不高。
3. 接口越来越多，markdown不能自动分类生成导航、自动折叠，前端找接口很麻烦，后端也难于维护。
4. 改了接口不止要改markdown，还要复制到wiki，容易忘记或者不同步。
5. 不能根据API自动生成Mock Server，在后端做好接口开发前，前端需要自己写假数据开发，费时费力。

以上问题总结起来，解决方案需要满足以下几点：
1.一个完整、统一的文档撰写规范
2.易于阅读的展示方式
3.便于维护、不需要多处修改的撰写方式
4.能够根据API文档生成Mock Server，以便于前端开发

Swagger Editor可以解决1、3、4，不止具有语法提示、语法检测，还支持定义对象，一处定义多处使用，减少重复编写，写好后可以一键生成Mock Server，而且支持生成多种语言的：

Swagger Editor

Swagger UI则是一套Web展示框架，把你用Swagger Editor写出来的东西，漂亮地展示出来：

Swagger UI

一、Swagger的使用概述

Swagger使用方式

二、 使用Swagger Editor撰写文档

1. 安装Swagger Editor

首先，安装Editor，安装方式多种可选。
最简单的就是使用Docker，只需要pull镜像，run镜像，就可以使用了，完全不用任何多余步骤。
不推荐在线Editor，亲测特别慢，毕竟是国外的服务器。

2. 撰写文档

此处有两个概念，不要混淆：语法（YAML或者JSON和规范（OpenAPI）。
OpenAPI规范就是我们期望的一套API撰写的完整规范，包括如何说明参数、请求方法、响应码、响应体等。
YAML和JSON是Swagger Editor能够读懂的语法。
用YAML或者JSON写出符合OpenAPI规范的文档 = 用JavaScript写出符合Restful规范的接口

1. 学习YAML语法
2. 学习OpenAPI规范

建议打开Swagger的在线Editor，对照着示例，边看边敲边学。

三、 使用Swagger UI展示文档

我们希望文档能跟在项目中，项目部署到服务器后，可以在项目服务器浏览到文档，而不用单独管理文档。

1. 部署Swagger UI到项目

1. 首先，在github下载Swagger UI的zip包，
2. 解压后，复制整个dist文件夹至public目录下，并改名为api-docs（随你喜欢）：

目录结构

2. 保存文档到项目

1. 在Swagger Editor中把文档保存为YAML或者JSON，我命名为swagger.yaml(或者json)，你可以随便改名：

   
   
   

   保存文档
2. 将文档放进api-docs文件夹，也就是Swagger UI的目录
3. 告诉Swagger UI，你需要显示的文档在这里：打开api-docs文件夹中的index.html，找到末尾的JavaScript，将url从http://petstore.swagger.io/v2/swagger.json修改为你的文档地址：

修改url

4. 启动你的项目，访问localhost:3000/api-docs，Duang，文档出现了！

   
   
   

   文档

三、 使用Swagger Editor生成Mock Server

非常简单，在Editor中选择Generate Server，选择你想要的语言就可以：

Generate Server

四、More

1. 从注释生成文档

我们之前使用Swagger Editor编辑文档，也可以借助框架，从注释生成文档，而不使用Editor。

• 安装swagger-jsdoc
• 配置swagger对象：

const swaggerJSDoc = require('swagger-jsdoc');

// swagger definition
const swaggerDefinition = {
  info: {
    title: '友分销API',
    version: '2.1.0',
    description: 'since 友分销2.0',
  },
  host: 'localhost:3000',
  basePath: '/',
};


// initialize swagger-jsdoc
module.exports = function () {
  // options for the swagger docs
  const options = {
    // import swaggerDefinitions
    swaggerDefinition: swaggerDefinition,
    // path to the API docs
    apis: ['../routes/*.js'],
  };
  return swaggerJSDoc(options)
};

• 由于是从注释动态生成，因此没有静态的文档文件，所以需要一个路由：

const router = module.exports = require('koa-router')();
const Swagger = require('../libs/swagger');
// serve swagger
router.get('/swagger.json', async function (ctx) {
  ctx.set('Content-Type', 'application/json');
  const swaggerSpec = Swagger();
  ctx.body = swaggerSpec;
});

• 在Swagger UI中将url设置为这个url
• 启动项目，访问Swagger UI，done！

2. 根据注释文档，生成Mock Server

使用swagger-tools的swagger-router中间件即可实现，具体没有测试，待大家发现。

参考

• 使用 Swagger 构建 Express API Server 的文档系统
• Swagger UI教程 API 文档神器 搭配Node使用