介紹
領(lǐng)導(dǎo)讓后端的同學(xué)寫一個mock server配合測試，所以一下子想到了Swagger這個東西望众，但是本人沒有用過匪补，所以打算寫一份菜鳥用的Swagger教程。
相信無論是前端還是后端開發(fā)烂翰，都或多或少地被接口文檔折磨過夯缺。前端經(jīng)常抱怨后端給的接口文檔與實(shí)際情況不一致。后端又覺得編寫及維護(hù)接口文檔會耗費(fèi)不少精力甘耿，經(jīng)常來不及更新踊兜。其實(shí)無論是前端調(diào)用后端，還是后端調(diào)用后端佳恬，都期望有一個好的接口文檔捏境。但是這個接口文檔對于程序員來說于游，就跟注釋一樣，經(jīng)常會抱怨別人寫的代碼沒有寫注釋垫言，然而自己寫起代碼起來贰剥，最討厭的，也是寫注釋筷频。所以僅僅只通過強(qiáng)制來規(guī)范大家是不夠的蚌成，隨著時間推移，版本迭代凛捏，接口文檔往往很容易就跟不上代碼了担忧。
Swagger是什么？它能干什么坯癣？
發(fā)現(xiàn)了痛點(diǎn)就要去找解決方案瓶盛。解決方案用的人多了，就成了標(biāo)準(zhǔn)的規(guī)范示罗，這就是Swagger的由來惩猫。通過這套規(guī)范，你只需要按照它的規(guī)范去定義接口及接口相關(guān)的信息鹉勒。再通過Swagger衍生出來的一系列項(xiàng)目和工具帆锋，就可以做到生成各種格式的接口文檔，生成多種語言的客戶端和服務(wù)端的代碼禽额，以及在線接口調(diào)試頁面等等。這樣皮官，如果按照新的開發(fā)模式脯倒，在開發(fā)新版本或者迭代版本的時候常摧，只需要更新Swagger描述文件铛碑，就可以自動生成接口文檔和客戶端服務(wù)端代碼，做到調(diào)用端代碼杨帽、服務(wù)端代碼以及接口文檔的一致性摄乒。
但即便如此悠反，對于許多開發(fā)來說，編寫這個yml或json格式的描述文件馍佑，本身也是有一定負(fù)擔(dān)的工作斋否，特別是在后面持續(xù)迭代開發(fā)的時候，往往會忽略更新這個描述文件拭荤，直接更改代碼茵臭。久而久之，這個描述文件也和實(shí)際項(xiàng)目漸行漸遠(yuǎn)舅世，基于該描述文件生成的接口文檔也失去了參考意義旦委。所以作為Java屆服務(wù)端的大一統(tǒng)框架Spring奇徒，迅速將Swagger規(guī)范納入自身的標(biāo)準(zhǔn)，建立了Spring-swagger項(xiàng)目缨硝，后面改成了現(xiàn)在的Springfox摩钙。通過在項(xiàng)目中引入Springfox，可以掃描相關(guān)的代碼查辩，生成該描述文件腺律，進(jìn)而生成與代碼一致的接口文檔和客戶端代碼。這種通過代碼生成接口文檔的形式宜肉，在后面需求持續(xù)迭代的項(xiàng)目中匀钧，顯得尤為重要和高效。
框架說明及使用
現(xiàn)在SWAGGER官網(wǎng)主要提供了幾種開源工具谬返，提供相應(yīng)的功能之斯。可以通過配置甚至是修改源碼以達(dá)到你想要的效果遣铝。
Swagger Codegen: 通過Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔佑刷，同時也能生成多鐘語言的服務(wù)端和客戶端的代碼。支持通過jar包酿炸，docker瘫絮，node等方式在本地化執(zhí)行生成。也可以在后面的Swagger Editor中在線生成填硕。
Swagger UI:提供了一個可視化的UI頁面展示描述文件麦萤。接口的調(diào)用方、測試扁眯、項(xiàng)目經(jīng)理等都可以在該頁面中對相關(guān)接口進(jìn)行查閱和做一些簡單的接口請求壮莹。該項(xiàng)目支持在線導(dǎo)入描述文件和本地部署UI項(xiàng)目。
Swagger Editor: 類似于markendown編輯器的編輯Swagger描述文件的編輯器姻檀，該編輯支持實(shí)時預(yù)覽描述文件的更新效果命满。也提供了在線編輯器和本地部署編輯器兩種方式。
Swagger Inspector: 感覺和postman差不多绣版，是一個可以對接口進(jìn)行測試的在線版的postman胶台。比在Swagger UI里面做接口請求，會返回更多的信息杂抽，也會保存你請求的實(shí)際請求參數(shù)等數(shù)據(jù)诈唬。
Swagger Hub：集成了上面所有項(xiàng)目的各個功能，你可以以項(xiàng)目和版本為單位默怨，將你的描述文件上傳到Swagger Hub中讯榕。在Swagger Hub中可以完成上面項(xiàng)目的所有工作，需要注冊賬號，分免費(fèi)版和收費(fèi)版愚屁。
PS：
Springfox Swagger: Spring 基于swagger規(guī)范济竹，可以將基于SpringMVC和Spring Boot項(xiàng)目的項(xiàng)目代碼，自動生成JSON格式的描述文件霎槐。本身不是屬于Swagger官網(wǎng)提供的送浊，在這里列出來做個說明，方便后面作一個使用的展開丘跌。
Swagger demo 代碼
啟動代碼
@MapperScan(basePackages = "com.liuliu.springboot.swagger2.mapper")
@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {
public static void main(String[] args) {
SpringApplication.run(SpringbootSwagger2Application.class, args);
}
}
在瀏覽器中輸入：
自動生成客戶端和服務(wù)端代碼
TODO
文章轉(zhuǎn)載自：
Swagger介紹及使用
SpringBoot整合Swagger2實(shí)現(xiàn)自動生成API(含源碼)
Swagger Codegen高效開發(fā)客戶端對接服務(wù)端代碼
