如何搭建Swagger介面文件
Swagger是規範RESTful API服務的語言或者說工具，不僅可以用來定義介面，還可以測介面，一舉兩得。
我不知道這個工具的流行程度如何，至少我知道的是網上的中文資料很少，也沒有如何在實際中使用起來的教程。經過一兩天的研究，總結一個簡單的搭建手冊。
Swagger的核心工具主要為三個：
Swagger-UI
：API展示和測試頁面
Swagger-Editor：所見即所得式編輯工具
Swagger-Codegen： 利用程式碼直接生成規範文件的工具
Swagger的規範文件是用yaml檔案或者json檔案來表述的，比如：
// yaml語法
swagger： “2。0”
info：
version： “1。0。0”
title： “Netease Seasons API”
description： “Netease seasons api docs”
termsOfService： “http：//helloreverb。com/terms/”
contact：
name： “野蠻的小小芬”
email： “Yecao@163。com”
license：
name： “MIT”
url： “http：//opensource。org/licenses/MIT”
host： “m。siji。163。com”
schemes：
- “http”
consumes：
- “application/json”
produces：
- “application/json”
- “application/xml”
paths：
/index。json：
get：
tags：
- “Homepage data”
description： “get the productList”
operationId： “getIndex”
produces：
- “application/json”
responses：
200：
description： “aqi response”
default：
description： “unexpected error”
用swagger-ui對應生成的頁面是這樣的：
使用Swagger來約定介面有兩種方式：
第一種，在編輯器中寫好文件，然後用Swagger-ui工具來展示；
第二種，在後端程式碼中按照約定的方式寫上一些註釋，使用Swagger-codegen自動掃描生成文件。
至於第二種方式，我也看了點網上的資料，但是後端的東西真的不懂，我就拋棄了。本文主要講講第一種方式，也是在前後端分離，並行開發的趨勢下比較適用的。下面一步一步地說明如何搭建一個Swagger專案。
新建一個專案，執行npm init初始化package。json。如果你的環境還沒有node的話，麻煩先安裝一下node，
npm命令
自然就可以用了；
執行npm install swagger -g ——save-dev安裝Swagger包；
在專案根目錄下，新建一個api/swagger/swagger。yaml，複製一個有效的yaml內容進來，為下一步做準備；
執行Swagger project edit，此時會自動開啟一個swagger編輯視窗，讀取的內容就是上一步中的
yaml檔案
；
嘗試修改編輯視窗的內容，此時右側會及時修改更新，而且api/swagger/swagger。yaml也會跟著自動更新
下載Swagger-ui，複製
dist資料夾
中的程式碼到根目錄下新建的public資料夾；
由於swagger-ui不能本地執行，藉助node的express建立一個服務，在根目錄下建立index。js，程式碼如下：
// 先安裝依賴的express，opn包
var express = require（‘express’）；
var app = express（）；
var opn = require（‘opn’）；
app。listen（3000， function （） {
opn（‘http：//localhost：3000/api-doc’）；
console。log（‘App listening on port 3000！’）；
}）；
app。use（‘/api-doc’， express。static（‘public’））；
8。 執行node index。js會啟用swagger-ui功能，自動開啟api展示頁面，但是頁面是預設的官網上的東西；
9。 將api/swagger資料夾下的/swagger。yaml檔案複製到public資料夾下，開啟public/index。html，在指令碼中修改url為‘。/
swagger。yaml
’，重新整理瀏覽器，即可看到我們的內容
10。 如何將swagger-editor檔案的變化實時反饋到swagger-ui上，執行npm install gulp -g ——save-dev安裝gulp包，在根目錄下新建
gulpfile。js
，程式碼如下：//記得先安裝好依賴
var gulp = require（‘gulp’）；
var yaml = require（‘
js-yaml
’）；
var path = require（‘path’）；
var fs = require（‘fs’）；
// 建立api/swagger的swagger。yaml到public下的swagger。yaml聯絡
gulp。task（‘swagger’， function（）{
var doc = yaml。safeLoad（fs。readFileSync（path。join（__dirname， ‘。/api/swagger/swagger。yaml’）））；
fs。writeFile（path。join（__dirname， ‘。/public/swagger。yaml’）， JSON。stringify（doc，null，‘ ’））；
}）；
// 實時更新
gulp。task（‘default’， function（）{
gulp。watch（‘。/api/swagger/swagger。yaml’，［‘swagger’］）；
}）
11。 到此，整個專案的依賴如下，都寫在package。json裡面，順便也設定了npm的script：
{
“name”： “
api-docs
”，
“version”： “1。0。0”，
“description”： “”，
“main”： “index。js”，
“scripts”： {
“start”： “node
index。js
”，
“swagger”： “swagger project edit”，
“gulp”： “gulp”
}，
“repository”： {
“type”： “git”，
“url”： “git+https：//github。com/swagger-api/swagger-ui。git”
}，
“author”： “”，
“license”： “ISC”，
“devDependencies”： {
“express”：“^4。15。2”，
“swagger”：“0。7。5”，
“gulp”：“3。9。1”，
“js-yaml”：“3。8。3”，
“opn”：“5。0。0”
}，
“bugs”： {
“url”： “https：//github。com/swagger-api/swagger-ui/issues”
}，
“homepage”： “https：//github。com/swagger-api/swagger-ui#readme”
}
12。 如果是多人協作的專案，建立一個git倉庫，進行版本管理，使得介面文件的統一；
13。 新建README。md，新增使用說明：
## api-docs
master分支是專案模板，一個專案開出一個分支來寫介面文件
此專案主要用來定義開發過程中的前後端介面
定義介面是用yaml或者json檔案來寫的，規範請參考［OpenAPI使用說明］（https：//github。com/OAI/OpenAPI-Specification/blob/master/versions/2。0。md）
使用方式：
1。 npm install 安裝需要的包
2。 npm start 開啟swagger ui，測介面
3。 npm run swagger 開啟編輯api視窗
4。 npm run gulp 實時監聽swagger editor的變化到swagger ui
5。 npm run help 可以檢視openAPI文件
如有不正確之處，歡迎指正！
作者：野草 20170505 首發地址
參考資料：
Swagger官網-如何起步
Swagger官網文件
Swagger論壇
Youtobe影片 Swagger： How to Create an API Documentation
使用Swagger外掛豐富增強RESTful服務
Swagger - 前後端分離後的契約
使用Swagger描述REST風格的API
Swagger與SpringMVC專案整合
Swagger初探
app後端開發一：swagger-ui教程-構建api介面文件工具
swagger ui教程，API文件生成神器
Java Documenting a REST API with Swagger and Spring MVC
