5分鐘了解swagger
5分鐘了解swagger
https://blog.csdn.net/i6448038/article/details/77622977
隨著互聯網技術的發展，現在的網站架構基本都由原來的後端渲染，變成了：前端渲染、先後端分離的形態，而且前端技術和後端技術在各自的道路上越走越遠。
前端和後端的唯一聯系，變成了API接口；API文檔變成了前後端開發人員聯系的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架。
其他API文檔工具
沒有API文檔工具之前，大家都是手寫API文檔的，在什麽地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md
書寫API文檔的工具有很多，但是能稱之為“框架”的，估計也只有swagger了。
在此先介紹一款其他的API文檔工具，叫rap，這玩意兒用一句話就能概括：解放生產力，代替手寫API的web工具。
RAP寫起來確實比手寫文檔要快，看看圖就知道：
可以選擇某個項目，寫針對某個項目的API
請看，可以填寫請求和相應的字段
還可以選擇字段對應的類型
類似的API文檔工具網上還有很多，但是能拿上臺面的，不多。RAP是由阿裏開發的，整個阿裏都在用，還不錯。github地址為：https://github.com/thx/RAP
rap不可能只有線上版本，肯定可以部署到私服上。 https://github.com/thx/RAP/wiki/deploy_manual_cn
swagger
rap挺好的，但是和swagger比起來有點輕量。
先看看swagger的生態使用圖：
其中，紅顏色的是swaggger官網方推薦的。
下面再細看看swagger的生態的具體內容：
swagger-ui
這玩意兒從名字就能看出來，用來顯示API文檔的。和rap不同的是，它不可以編輯。
點擊某個詳細API的可以試。
swagger-editor
就是一個在線編輯文檔說明文件（swagger.json或swagger.yaml文件）的工具，以方便生態中的其他小工具（swagger-ui）等使用。
編輯swagger說明文件使用的是yaml語法具體的內容可以去官網查看。
各種語言版本的根據annotation或者註釋生成swagger說明文檔的工具
目前最流行的做法，就是在代碼註釋中寫上swagger相關的註釋，然後，利用小工具生成swagger.json或者swagger.yaml文件。
目前官方沒有推出。github上各種語言各種框架各種有，可以自己搜吧搜吧，這裏只說一個php相關的。
swagger-php :https://github.com/zircote/swagger-php
swagger-validator
這個小工具是用來校驗生成的文檔說明文件是否符合語法規定的。用法非常簡單，只需url地址欄，根路徑下加上一個參數url，參數內容是放swagger說明文件的地址。即可校驗。
例如：
docker hub地址為：https://hub.docker.com/r/swaggerapi/swagger-validator/
可以pull下鏡像來自己玩玩。
swagger-codegen
代碼生成器，腳手架。可以根據swagger.json或者swagger.yml文件生成指定的計算機語言指定框架的代碼。
有一定用處，Java系用的挺多。工業上應該不咋用。
mock server
這個目前還沒有找到很合適的mock工具，包括rap也好，其他API文檔工具也好，都做的不夠完善，大多就是根據說明文件，例如swagger.json等生成一些死的靜態的mock數據，不能夠根據限定條件：例如“只能是數字，必傳”等做出合理的回應。
5分鐘了解swagger