Swagger是一個(gè)編寫(xiě)API文檔的套件組合冠句，而不是一個(gè)單一的工具听隐。具體可以在官網(wǎng)看到军拟。
Swagger可以實(shí)現(xiàn)很多功能剃执，這里只說(shuō)最基礎(chǔ)、常用的：
1. API文檔撰寫(xiě) —— Swagger Editor
2. API文檔的顯示 —— Swagger UI
3. 生成Mock服務(wù) —— Swagger Editor
目前我們很多項(xiàng)目采用的都是新建一個(gè)markdown懈息，寫(xiě)文檔肾档，每次改接口，就打開(kāi)舊的markdown=>編輯=>保存=>復(fù)制并發(fā)布到項(xiàng)目wiki辫继。
這種方式面臨的問(wèn)題：
1. 撰寫(xiě)方式?jīng)]有具體的規(guī)范怒见，每個(gè)后端都有自己的寫(xiě)法，不利于前端理解姑宽、項(xiàng)目交接遣耍。
2. 由于API文檔往往涉及到復(fù)雜的參數(shù)說(shuō)明、返回值說(shuō)明炮车，markdown顯示復(fù)雜的文檔其實(shí)并不美觀舵变、可讀性不高。
3. 接口越來(lái)越多瘦穆，markdown不能自動(dòng)分類(lèi)生成導(dǎo)航纪隙、自動(dòng)折疊，前端找接口很麻煩扛或，后端也難于維護(hù)绵咱。
4. 改了接口不止要改markdown，還要復(fù)制到wiki熙兔，容易忘記或者不同步悲伶。
5. 不能根據(jù)API自動(dòng)生成Mock Server，在后端做好接口開(kāi)發(fā)前住涉，前端需要自己寫(xiě)假數(shù)據(jù)開(kāi)發(fā)麸锉，費(fèi)時(shí)費(fèi)力。
以上問(wèn)題總結(jié)起來(lái)秆吵，解決方案需要滿足以下幾點(diǎn)：
1.一個(gè)完整淮椰、統(tǒng)一的文檔撰寫(xiě)規(guī)范
2.易于閱讀的展示方式
3.便于維護(hù)、不需要多處修改的撰寫(xiě)方式
4.能夠根據(jù)API文檔生成Mock Server纳寂，以便于前端開(kāi)發(fā)
Swagger Editor可以解決1、3泻拦、4毙芜，不止具有語(yǔ)法提示、語(yǔ)法檢測(cè)争拐，還支持定義對(duì)象腋粥，一處定義多處使用晦雨，減少重復(fù)編寫(xiě)，寫(xiě)好后可以一鍵生成Mock Server隘冲，而且支持生成多種語(yǔ)言的：
Swagger UI則是一套Web展示框架闹瞧，把你用Swagger Editor寫(xiě)出來(lái)的東西，漂亮地展示出來(lái)：
一展辞、Swagger的使用概述
二奥邮、 使用Swagger Editor撰寫(xiě)文檔
1. 安裝Swagger Editor
首先，安裝Editor罗珍，安裝方式多種可選洽腺。
最簡(jiǎn)單的就是使用Docker，只需要pull鏡像覆旱，run鏡像蘸朋，就可以使用了，完全不用任何多余步驟扣唱。
不推薦在線Editor藕坯，親測(cè)特別慢，畢竟是國(guó)外的服務(wù)器噪沙。
2. 撰寫(xiě)文檔
此處有兩個(gè)概念堕担，不要混淆：語(yǔ)法（YAML或者JSON和規(guī)范（OpenAPI）。
OpenAPI規(guī)范就是我們期望的一套API撰寫(xiě)的完整規(guī)范曲聂，包括如何說(shuō)明參數(shù)霹购、請(qǐng)求方法、響應(yīng)碼朋腋、響應(yīng)體等齐疙。
YAML和JSON是Swagger Editor能夠讀懂的語(yǔ)法。
用YAML或者JSON寫(xiě)出符合OpenAPI規(guī)范的文檔 = 用JavaScript寫(xiě)出符合Restful規(guī)范的接口
- 學(xué)習(xí)YAML語(yǔ)法
- 學(xué)習(xí)OpenAPI規(guī)范
建議打開(kāi)Swagger的在線Editor旭咽，對(duì)照著示例贞奋，邊看邊敲邊學(xué)。
三穷绵、 使用Swagger UI展示文檔
我們希望文檔能跟在項(xiàng)目中轿塔，項(xiàng)目部署到服務(wù)器后，可以在項(xiàng)目服務(wù)器瀏覽到文檔仲墨，而不用單獨(dú)管理文檔勾缭。
1. 部署Swagger UI到項(xiàng)目
- 首先，在github下載Swagger UI的zip包目养，
- 解壓后俩由，復(fù)制整個(gè)
dist文件夾至public目錄下，并改名為api-docs（隨你喜歡）：
2. 保存文檔到項(xiàng)目
-
在Swagger Editor中把文檔保存為YAML或者JSON癌蚁，我命名為swagger.yaml(或者json)幻梯，你可以隨便改名：
保存文檔 - 將文檔放進(jìn)api-docs文件夾兜畸，也就是Swagger UI的目錄
- 告訴Swagger UI，你需要顯示的文檔在這里：打開(kāi)api-docs文件夾中的index.html碘梢，找到末尾的JavaScript咬摇，將url從http://petstore.swagger.io/v2/swagger.json修改為你的文檔地址：
-
啟動(dòng)你的項(xiàng)目，訪問(wèn)localhost:3000/api-docs煞躬，Duang肛鹏，文檔出現(xiàn)了！
文檔
三汰翠、 使用Swagger Editor生成Mock Server
非常簡(jiǎn)單龄坪，在Editor中選擇Generate Server，選擇你想要的語(yǔ)言就可以：
四复唤、More
1. 從注釋生成文檔
我們之前使用Swagger Editor編輯文檔健田，也可以借助框架，從注釋生成文檔佛纫，而不使用Editor妓局。
- 安裝swagger-jsdoc
- 配置swagger對(duì)象：
const swaggerJSDoc = require('swagger-jsdoc');
// swagger definition
const swaggerDefinition = {
info: {
title: '友分銷(xiāo)API',
version: '2.1.0',
description: 'since 友分銷(xiāo)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)
};
- 由于是從注釋動(dòng)態(tài)生成，因此沒(méi)有靜態(tài)的文檔文件呈宇，所以需要一個(gè)路由：
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設(shè)置為這個(gè)url
- 啟動(dòng)項(xiàng)目好爬，訪問(wèn)Swagger UI，done甥啄！
2. 根據(jù)注釋文檔存炮，生成Mock Server
使用swagger-tools的swagger-router中間件即可實(shí)現(xiàn)，具體沒(méi)有測(cè)試蜈漓，待大家發(fā)現(xiàn)穆桂。
