用過swagger的能不能說下怎麼開始用？從安裝開始。。

03-15

小白求助ing,感覺好心累，英文不好，github上它的開發指南，配置指南都是英文，偏偏這方面的搜百度並沒有什麼有用的教程，我現在還停留在第一步，心中充滿了疑問：swagger editor是要從github上把它下下來使用嗎？還是它官網上有個在線的swagger editor，從github上有把它下下來，可是並不知道點什麼開始，如果是編輯那個在線的swagger editor，那編輯好之後呢，怎麼運用到自己的項目中去。
抱歉在話題中找不到 swagger.

https://zhuanlan.zhihu.com/p/21353795

我昨天試了一下，發現還是 docker 的方式運行比較快速：

** swagger-ui **

docker pull swaggerapi/swagger-ui

docker run -p 4000:8080 swaggerapi/swagger-ui

打開 http://localhost:4000 就可以看到

** swagger-editor **

docker pull swaggerapi/swagger-editor

docker run -p 5000:8080 swaggerapi/swagger-editor

打開 http://localhost:5000 就可以看到

我目前也剛接觸，swagger 有兩種用法：

直接通過在 java 代碼中下加入注釋的方式，然後自動生成 spec 供 swagger-ui 消費
獨立編寫 swagger spec，然後保存為 json 格式，然後，供 swagger-ui 消費

總的來說， swagger-ui 使用用來消費查閱 swagger spec 描述的 api 的，swagger-editor 就是用來編輯 swagger spec 的。

首先要明白swagger可以根據代碼注釋生成api文檔,也可以自己根據open api的規範書寫.對於後者,推薦閱讀:Swagger從入門到精通.

但是按照這個規範自己手寫起來真的好麻煩,這裡推薦一個在線的基於swagger的工具:

sosoapi,容易上手,特別好用.

剛好也用到，今天研究了一下，也花不了少時間，搞明白後又發現其實並不難。

-------------------------

因為swagger使用的是nodejs 所以第一步，你電腦上要安裝這個環境。apt-get install nodejs npm

swagger editor是要從github上把它下下來使用嗎？？

其實是不用下下來的，Swagger Editor 在線編輯後，點擊「Genernate Server」下拉項後選擇「Node.js」,就會下載一個壓縮包，解壓後，命令行cd到這個目錄後輸入命令：npm install 安裝依賴後 npm start 啟動後，訪問 http://localhost:8080/docs 即可。
另一種方式就是到 swagger-api/swagger-ui 這裡git clone這個項目下來，npm install 後 npm run build 會在 ./dist 生成你所需要的文件，這個可以放在容器里訪問（如Tomcat/webapps/dist,則訪問地址就是http://localhost:8080/dist/index.html）,也可以直接雙擊打開。打開後會發現跟上一種方式打開的界面是一樣的。不過這時候需要你錄入一個swagger.json的地址，這個文件是從Swagger Editor 在線編輯後，點擊「File」下拉項後選擇「Download JSON」,就會下載這個文件了。將這個文件放到(Tomcat/webapps/dist目錄下)，然後就可以使用地址訪問，將該地址錄入進去，點擊Explore, 即可。

----------------------------------

兩種方式有一點點不一樣就是：第一種不知道在那裡設置切換語言，第二種很方便就可以切換語言。

----------------------------

好了。如果你不想使用Swagger Editor 在線編輯。也是可以的。你可以git clone swagger-api/swagger-editor 這個項目下來。 npm install 後npm start啟動，或者npm run build後生成的dist目錄+config+docs+images+spec-files+templates+test+views+index.html+404.html這些目錄和文件放到容器里啟動。（我就是卡在這裡的。我clone下來後npm install很久都沒反應，最後沒轍就借了一台EC2的，在雲端操作就好了，然後tar打包下載後就正常使用了。）

使用spring-boot-starter-swagger實現API文檔化

使用太繁瑣了，還不如一個小工具WisdomTool REST Client，點個按鈕就生成了，完全脫離代碼，不懂代碼的小白都能使用它生成API文檔。

最近在用這個東西，使用swagger之前你要先理解什麼是RESTful ,然後才能做出滿意的API。

用法其實很簡單，假如你的項目是使用Spring Boot框架的話，只需要使用swagger editor編輯你的RESTful API導出成yaml文件。然後使用codegen 生成你需要的API Jar包，然後把jar包引入到你的項目中就可以使用你在swagger中定義的API了，省去了非常多的代碼量。而且升級和維護都比較方便，前台也可生成client 包實現前後台分離的目的，升級和維護都非常方便。

忘記了，首先要添加依賴。。

Swagger-炫酷上手

可以看一下這篇博客 Swagger與SpringMvc集成生成Restful形式介面文檔 - 博客頻道 - CSDN.NET

加入是基於 Spring-Boot開發到話，你可以參照下我這篇教程。 Swagger2 生成 Spring Boot API 文檔

額，我們之前也是直接用的swagger ui，不過編輯和維護太麻煩了，團隊內部推廣學習成本比較高。後來經過調研，我們選擇sosoapi,可以理解為swagger ui的可視化編輯，非常容易上手，而且還有團隊協作功能。

swagger editor 按照文檔安裝後會自動幫你在瀏覽器中打開。

然後就直接編寫即可，會自動幫你保存。