轉自：https://zhuanlan.zhihu.com/p/26741562
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