Swagger 是一款RESTFUL接口的、基於YAML、JSON語言的文檔在線自動生成、代碼自動生成的工具。
官網地址
概述
我將通過以下幾點來介紹Swagger這個強大的工具：
-
環境集成
-
功能介紹
-
文檔編寫
-
代碼生成
-
自定義代碼生成模板
集成步驟
進入 https://swagger.io/docs/swagger-tools/ 這個網址，可以看到，文檔的編寫可以有遠程和本地兩種方式：
-
遠程方式：
-
本地方式:
基於node.js、npm、http-server， 如果還沒有安裝node環境的同學可以參考 Node安裝教程。
npm install -g http-server // 安裝 http-serverwget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip // 不用wget命令也可以，復制鏈接去下載zip包unzip swagger-editor.zip // 解壓下載的zip包http-server swagger-editor // 啟動 swagger
打開 http://127.0.0.1:8080/#/，之后你可以看到與遠程方式相同的頁面:
至此，編輯環境搭建完成~
功能介紹
-
你可以引用本地的json、yaml文件，也可以新建，編寫完成后下載。
-
在線測試，文檔編寫完后，可以點擊
try this operation進行接口測試。
-
強大的代碼生成，編寫完文檔后可以下載相應的代碼。
文檔編寫
-
也可以參考中文文檔https://www.gitbook.com/book/huangwenchao/swagger/details
這里着重說一下ref語法，鑒於 所有model不可能寫在同一個文件里，那么就會引用其他文件的model，如圖，
當我們本地執行 http-server swagger-editor 時，其實 127.0.0.1:8080 指向的根目錄就是 swagger-editor 目錄，我們在 根目錄中可以添加、修改 json或者yaml文件，供ref引用，切忌！每次修改之后一定要重新執行 http-server swagger-editor ，否則 127.0.0.1:8080 映射的目錄中將沒有最新的修改。
代碼生成
在功能介紹的地方已經介紹了如何快捷地通過網頁去生成對應平台的代碼，但出於最后要說 自定義代碼生成模板，所以這里的代碼生成主要是介紹如何通過命令去生成代碼，這里我們參考的是https://github.com/swagger-api/swagger-codegen，由於工程整個是以maven構建的，所以如果沒有安裝maven的同學可以先使用 brew install maven進行maven的安裝：
-
克隆倉庫並且build工程
git clone https://github.com/swagger-api/swagger-codegen // 克隆倉庫cd swagger-codegen mvn clean package // build 工程
這樣就會生成 swagger-codegen-cli.jar文件，
我們來看一下swagger-codegen的工程結構
-
接下來我們可以執行命令來生成sample代碼了
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i http://petstore.swagger.io/v2/swagger.json \ -l java \ -o samples/client/petstore/java// -i 指向文檔 -o 指向生成目錄 -l 指向 modules中的模板(可以理解為語言)
自定義代碼生成模板
當然，在我們的實際使用中，官方提供的代碼生成模板是很可能不滿足需求的，這樣，就需要我們自己去寫模板，模板需要使用mustache語言 ：
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar meta \ -o output/myLibrary -n myClientCodegen -p com.my.company.codegen
執行命令后會生成模板工程：
我們需要修改 上圖的 java 中的MyclientcodegenGenerator.java 和 resource 中的 *.mustache文件，具體如何修改，我也是個入門選手，細節就不做過多說明，這里着重講下流程，建議參考 modules 中官方自帶的那些模板是如何編寫的。模板生成好了，那么就執行驗證一下：
java -cp output/myLibrary/target/myClientCodegen-swagger-codegen-1.0.0.jar:modules/swagger-codegen-cli/target/swagger-codegen-cli.jar io.swagger.codegen.SwaggerCodegen
如上圖，說明我們的模板已經可以使用了，那么來生成個文檔試試~
java -cp output/myLibrary/target/myClientCodegen-swagger-codegen-1.0.0.jar:modules/swagger-codegen-cli/target/swagger-codegen-cli.jar \ io.swagger.codegen.SwaggerCodegen generate -l myClientCodegen\ -i http://petstore.swagger.io/v2/swagger.json \ -o myClient
以上過程如果報 myFile.mustache找不到，原因是：
創建一個空的 myFile.mustache文件即可。大功告成，生成后的工程如下：
好了，這篇文章就分享到這里，至於mustache語法，本篇沒有細講，做前端的同學可能比較了解，客戶端的同學。。。。。。額，可以自行百度，有很多講 mustache 語法的教程。
原文鏈接：http://www.apkbus.com/blog-487165-76803.html
作者：喵喔喔
鏈接：https://www.imooc.com/article/71842
來源：慕課網