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中間件即可實現，具體沒有測試，待大家發現。
