前言
在做前後端分離的項目過程中，後端的接口文檔更新維護的工作量很大。開發過程中接口發生變更，不僅要修改接口代碼，還需要及時的修改接口文檔。傳統接口文檔都是用word或excel進行記錄編輯，而且還需要配合接口調用工具或到瀏覽器中進行接口的調用測試。這時候使用這套可視化，規範化的自動接口生成文檔工具就會更加方便開發測試了。在工具頁面中可以直接填寫輸入參數進行接口調用，不用再自己複製url鏈接去測試接口了。
總體思路
在swagger-editor中編寫好了api文檔，再放到swagger-ui中去預覽，同時進行調用測試。
具體實現
一、sawgger editor編輯
1.swagger-editor 環境搭建
（1）安裝node、npm、http-server
（2）從官網 https://github.com/swagger-api/swagger-editor 下載swagger editor並解壓到任意文件夾
（3）cmd命令行cd到swagger editor解壓路徑，然後輸入 http-server 命令顯示啓動成功
（默認爲8080端口，修改端口 運行命令 http-server –p 端口號）
（4）訪問： http://127.0.0.1:8080
2.成功運行sawgger editor後，在左側代碼欄內進行編輯，右側可以看效果也可以進行接口的調試
接口測試：右側展示區內點擊“Try this operation”按鈕，輸入參數並點擊“Send Request”即可看到接口調用結果
3.編輯完成後下載json文件（生成文件swagger.json，後續需要放到展示的前端項目中）
二、sawgger UI展示
1.swagger-ui 環境搭建
（1）進入官網下載ui項目，並解壓
https://github.com/swagger-api/swagger-ui/tree/2.x
（2）進行nodejs配置
mkdir node_app 新建node_app文件夾，
cd node_app 初始化node，輸入好信息後會自動創建package.json文件
npm init 初始化命令，出現如下信息，填的地方可以隨便寫，也可以不寫
（3）swagger-ui中的dist文件夾拷貝到node_app下：
（4）安裝express
npm install express 如果出錯可以去nodejs安裝目錄進行安裝
（5）創建index.js
echo.>index.js 創建index.js
並將如下代碼寫入該js中:
var express = require('express');
var app = express();
app.use('/root', express.static('dist'));
app.get('/', function (req, res) {
res.send('Hello World!');
});
app.listen(3000, function () {
console.log('Example app listening on port 3000!');
});
2.更新json文件
（1）找到項目的dist文件夾內的index.html代碼文件
（2）更新代碼文件中json的url
url = "http://petstore.swagger.io/v2/swagger.json"; --> url = "/root/swagger.json";
（3）將Sawwger Editor中生成的swagger.json文件，放置index.html同級路徑下
（每當接口有所更新，則需要重新生成該文件）
3.運行sawgger UI進行展示
（1）cmd命令框轉到sawwger ui項目所在的路徑，執行命令node index.js 運行項目
（2）瀏覽器輸入地址 http://127.0.0.1:3000/root/index.html 即可運行查看（index.js中代碼爲3000端口，可自行修改）
*注：swagger-editor參數詳情
Swagger API Spec包含以下部分：
- swagger，指定swagger spec版本，2.0
- info，提供API的元數據
- tags，補充的元數據，在swagger ui中，用於作爲api的分組標籤
- host，主機，如果沒有提供，則使用文檔所在的host
- basePath，相對於host的路徑
- schemes，API的傳輸協議，http，https，ws，wss
- consumes，API可以消費的MIME類型列表
- produces，API產生的MIME類型列表
- paths，API的路徑，以及每個路徑的HTTP方法，一個路徑加上一個HTTP方法構成了一個操作。每個操作都有以下內容：
- tags，操作的標籤
- summary，短摘要
- description，描述
- externalDocs，外部文檔
- operationId，標識操作的唯一字符串
- consumes，MIME類型列表
- produces，MIME類型列表
- parameters，參數列表
- name，名字
- description，描述required，是否必須
- in，位置
- Path
- Query
- Header
- Body
- Form
- （對於Body類型的參數）
- schema，數據類型，可以詳細描述，也可以引用definition部分定義的schema
- （對於Body類型以外的參數）
- type，類型
- format，數據格式
- allowEmptyValue，是否允許空值
- items，對於Array類型
- collectionFormat，對於Array類型
- default，缺省值-默認值
- responses，應答狀態碼和對於的消息的Schema
- schemes，傳輸協議
- deprecated，不推薦使用
- security，安全
- definitions，定義API消費或生產的數據類型，使用json-schema描述，操作的parameter和response部分可以通過引用的方式使用definitions部分定義的schema
- parameters，多個操作共用的參數
- responses，多個操作共用的響應
- securityDefinitions，安全scheme定義
- security，安全聲明
- externalDocs，附加的外部文檔
參數詳情參考自 <https://www.cnblogs.com/jocongmin/articles/7082363.html>