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 UI则是一套Web展示框架，把你用Swagger Editor写出来的东西，漂亮地展示出来：
一、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规范的接口
建议打开Swagger的在线Editor，对照着示例，边看边敲边学。
三、 使用Swagger UI展示文档
我们希望文档能跟在项目中，项目部署到服务器后，可以在项目服务器浏览到文档，而不用单独管理文档。
1. 部署Swagger UI到项目
- 首先，在github下载Swagger UI的zip包，
- 解压后，复制整个
dist文件夹至public目录下，并改名为api-docs（随你喜欢）：
2. 保存文档到项目
-
在Swagger Editor中把文档保存为YAML或者JSON，我命名为swagger.yaml(或者json)，你可以随便改名：
保存文档 - 将文档放进api-docs文件夹，也就是Swagger UI的目录
- 告诉Swagger UI，你需要显示的文档在这里：打开api-docs文件夹中的index.html，找到末尾的JavaScript，将url从http://petstore.swagger.io/v2/swagger.json修改为你的文档地址：
-
启动你的项目，访问localhost:3000/api-docs，Duang，文档出现了！
文档
三、 使用Swagger Editor生成Mock Server
非常简单，在Editor中选择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中间件即可实现，具体没有测试，待大家发现。
