Swagger 是一款RESTFUL接口的、基于YAML宛瞄、JSON語(yǔ)言的文檔在線自動(dòng)生成已烤、代碼自動(dòng)生成的工具。
官網(wǎng)地址
概述
我將通過(guò)以下幾點(diǎn)來(lái)介紹Swagger這個(gè)強(qiáng)大的工具：
- 環(huán)境集成
- 功能介紹
- 文檔編寫
- 代碼生成
- 自定義代碼生成模板
集成步驟
進(jìn)入 https://swagger.io/docs/swagger-tools/ 這個(gè)網(wǎng)址停忿，可以看到，文檔的編寫可以有遠(yuǎn)程和本地兩種方式：
-
遠(yuǎn)程方式：image.png
本地方式:
基于node.js蜀涨、npm瞎嬉、http-server蝎毡， 如果還沒有安裝node環(huán)境的同學(xué)可以參考 Node安裝教程。
npm install -g http-server // 安裝 http-server
wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip
// 不用wget命令也可以氧枣，復(fù)制鏈接去下載zip包
unzip swagger-editor.zip // 解壓下載的zip包
http-server swagger-editor // 啟動(dòng) swagger
打開 http://127.0.0.1:8080/#/沐兵，之后你可以看到與遠(yuǎn)程方式相同的頁(yè)面:
至此，編輯環(huán)境搭建完成~
功能介紹
-
你可以引用本地的json便监、yaml文件扎谎，也可以新建，編寫完成后下載烧董。image.png
- 在線測(cè)試毁靶，文檔編寫完后，可以點(diǎn)擊
try this operation進(jìn)行接口測(cè)試逊移。image.png -
強(qiáng)大的代碼生成预吆，編寫完文檔后可以下載相應(yīng)的代碼。image.png
image.png
文檔編寫
- 可以參考官方文檔
https://swagger.io/docs/specification/about/ - 也可以參考中文文檔https://www.gitbook.com/book/huangwenchao/swagger/details
這里著重說(shuō)一下ref語(yǔ)法胳泉，鑒于 所有model不可能寫在同一個(gè)文件里拐叉，那么就會(huì)引用其他文件的model，如圖扇商，image.png
當(dāng)我們本地執(zhí)行http-server swagger-editor時(shí)凤瘦，其實(shí)127.0.0.1:8080指向的根目錄就是swagger-editor目錄，我們?cè)?根目錄中可以添加案铺、修改 json或者yaml文件蔬芥，供ref引用，切忌控汉！每次修改之后一定要重新執(zhí)行http-server swagger-editor笔诵，否則127.0.0.1:8080映射的目錄中將沒有最新的修改。
代碼生成
在功能介紹的地方已經(jīng)介紹了如何快捷地通過(guò)網(wǎng)頁(yè)去生成對(duì)應(yīng)平臺(tái)的代碼暇番，但出于最后要說(shuō) 自定義代碼生成模板嗤放，所以這里的代碼生成主要是介紹如何通過(guò)命令去生成代碼，這里我們參考的是https://github.com/swagger-api/swagger-codegen壁酬，由于工程整個(gè)是以maven構(gòu)建的，所以如果沒有安裝maven的同學(xué)可以先使用 brew install maven進(jìn)行maven的安裝：
- 克隆倉(cāng)庫(kù)并且build工程
git clone https://github.com/swagger-api/swagger-codegen // 克隆倉(cāng)庫(kù)
cd swagger-codegen
mvn clean package // build 工程
這樣就會(huì)生成 swagger-codegen-cli.jar文件恨课，
我們來(lái)看一下
swagger-codegen的工程結(jié)構(gòu)
- 接下來(lái)我們可以執(zhí)行命令來(lái)生成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中的模板(可以理解為語(yǔ)言)
自定義代碼生成模板
當(dāng)然舆乔，在我們的實(shí)際使用中，官方提供的代碼生成模板是很可能不滿足需求的剂公，這樣希俩，就需要我們自己去寫模板，模板需要使用mustache語(yǔ)言 ：
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar meta \
-o output/myLibrary -n myClientCodegen -p com.my.company.codegen
執(zhí)行命令后會(huì)生成模板工程：
我們需要修改 上圖的 java 中的
MyclientcodegenGenerator.java 和 resource 中的 *.mustache 文件纲辽，具體如何修改颜武，我也是個(gè)入門選手璃搜，細(xì)節(jié)就不做過(guò)多說(shuō)明，這里著重講下流程鳞上，建議參考 modules 中官方自帶的那些模板是如何編寫的这吻。模板生成好了，那么就執(zhí)行驗(yàn)證一下：
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
如上圖篙议，說(shuō)明我們的模板已經(jīng)可以使用了唾糯，那么來(lái)生成個(gè)文檔試試~
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
以上過(guò)程如果報(bào) myFile.mustache找不到，原因是：
創(chuàng)建一個(gè)空的
myFile.mustache文件即可鬼贱。大功告成移怯，生成后的工程如下：
好了，這篇文章就分享到這里这难，至于mustache語(yǔ)法舟误，本篇沒有細(xì)講，做前端的同學(xué)可能比較了解姻乓，客戶端的同學(xué)嵌溢。。糖权。堵腹。。星澳。額疚顷，可以自行百度，有很多講 mustache 語(yǔ)法的教程禁偎。
參考文獻(xiàn)
https://swagger.io/docs/
https://www.gitbook.com/book/huangwenchao/swagger/details
https://github.com/swagger-api/swagger-codegen#getting-started
