您好,登錄后才能下訂單哦!
一、前言
讓我們先理一下springfox與swagger的關(guān)系。
swagger是一個(gè)流行的API開發(fā)框架,這個(gè)框架以“開放API聲明”(OpenAPI Specification,OAS)為基礎(chǔ),對(duì)整個(gè)API的開發(fā)周期都提供了相應(yīng)的解決方案,是一個(gè)非常龐大的項(xiàng)目(包括設(shè)計(jì)、編碼和測試,幾乎支持所有語言)。
OAS本身是一個(gè)API規(guī)范,它用于描述一整套API接口,包括一個(gè)接口是GET還是POST請(qǐng)求啊,有哪些參數(shù)哪些header啊,都會(huì)被包括在這個(gè)文件中。它在設(shè)計(jì)的時(shí)候通常是YAML格式,這種格式書寫起來比較方便,而在網(wǎng)絡(luò)中傳輸時(shí)又會(huì)以json形式居多,因?yàn)?/span>json的通用性比較強(qiáng)。
由于Spring的流行,Marty Pitt編寫了一個(gè)基于Spring的組件swagger-springmvc,用于將swagger集成到springmvc中來。而springfox則是從這個(gè)組件發(fā)展而來,同時(shí)springfox也是一個(gè)新的項(xiàng)目,本文仍然是使用其中的一個(gè)組件springfox-swagger2。
pringfox-swagger2依然是依賴OSA規(guī)范文檔,也就是一個(gè)描述API的json文件,而這個(gè)組件的功能就是幫助我們自動(dòng)生成這個(gè)json文件,我們會(huì)用到的另外一個(gè)組件springfox-swagger-ui就是將這個(gè)json文件解析出來,用一種更友好的方式呈現(xiàn)出來。
這是入門,我們簡單地介紹springfox-swagger2的配置,幫助各位順利地實(shí)現(xiàn)使用,文中有很多自己的理解,若有錯(cuò)誤,歡迎批評(píng)指正。
二、配置流程說明
在開始編碼之前,我們先對(duì)配置的流程有個(gè)大致的了解。
在前言中,我們知道,我們的第一個(gè)任務(wù)就是生成一個(gè)滿足OSA規(guī)范的json文件(當(dāng)然,創(chuàng)建一個(gè)spring的項(xiàng)目就不說了)。對(duì)于這個(gè)任務(wù),springfox為我們提供了一個(gè)Docket(摘要的意思)類,我們需要把它做成一個(gè)Bean注入到spring中,顯然,我們需要一個(gè)配置文件,并通過一種方式(顯然它會(huì)是一個(gè)注解)告訴程序,這是一個(gè)Swagger配置文件。
一個(gè)OSA規(guī)范文檔需要許多信息來描述這個(gè)API,springfox允許我們將信息組合成一個(gè)ApiInfo的類,作為構(gòu)造參數(shù)傳給Docket(當(dāng)然也可以不構(gòu)造這個(gè)類,而直接使用null,但是你的這個(gè)API就太low了)。
接下來,我們要寫控制器了,當(dāng)然這不重要,不用springfox你依然要寫控制器,重要的是要告訴springfox,這個(gè)控制器是一個(gè)需要他來收集API信息的控制器,不用說,這依然會(huì)采用注解的方式,同時(shí),我們?yōu)榱藢⑴渲梦募c控制器結(jié)合起來,需要在配置文件中指明在什么位置收集可能是API的控制器的信息。
到這里,生成OSA規(guī)范的json文件的配置就結(jié)束了。雖然生成過程比我敘述的更復(fù)雜,但這些程序都會(huì)幫我們完成,我們可以通過類似http://localhost:8080/demo/v2/api-docs的路徑來查看這個(gè)json文件。這個(gè)v2/api-docs就是springfox默認(rèn)的生成文檔的路徑。
接下來,我們需要將它可視化顯示出來,如果使用swagger-springmvc,我們需要單獨(dú)去下載一個(gè)swagger ui的顯示頁面包,并將其中的路徑改為上面的http://localhost:8080/demo/v2/api-docs,這里你就可以感受到,swagger ui就是在解析一個(gè)json文件了。你依然可以這么做,不過springfox專門提供了一個(gè)springfox-swagger-ui組件,不需要配置,我們只需要引入這個(gè)依賴的組件就可以看到最終的效果了,而這個(gè)路由會(huì)是http://localhost:8080/demo/swagger-ui.html。
三、引入依賴
如果我寫的不錯(cuò),相信看到這里,你就大致了解了springfox swagger2的使用流程了。那么,我們進(jìn)入正式編碼的第一步:引入依賴。
這里我們使用maven引入依賴,大家可以到http://mvnrepository.com上搜索springfox,便可以看到Springfox Swagger2和Springfox Swagger Ui,然后就可以從中獲取最新的資源了。如下:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
此外還需要一個(gè)依賴組件:
<dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.6.6</version> </dependency>
四、一個(gè)簡單的配置文件
為了清晰,我們可以先在常用的源碼包里建一個(gè)config目錄,并在里面創(chuàng)建一個(gè)SwaggerConfig.java文件,這是一個(gè)spring的配置文件,所以位置和文件名都影響不大。
先上代碼:
@Configuration //必須存在 @EnableSwagger2 //必須存在 @EnableWebMvc //必須存在 @ComponentScan(basePackages = {"com.xiaoming.SpringMVC.controller"}) //必須存在 掃描的API Controller package name 也可以直接掃描class (basePackageClasses) public class SwaggerConfig{ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()); } private ApiInfo apiInfo() { Contact contact = new Contact("小明", "https://www.jb51.net/", "zhaomin0018@126.com"); return new ApiInfoBuilder() .title("前臺(tái)API接口") .description("前臺(tái)API接口") .contact(contact) .version("1.1.0") .build(); } }
由于各位肯定用的是IDE,這里就不寫各種import了。
首先,這個(gè)SwaggerConfig類有四個(gè)注解,看名稱就可以明白是什么意思。其中,@Configuration,@EnableWebMvc和@ComponentScan是Spring的注解,而@EnableSwagger2則是用來啟動(dòng)Swagger支持,表示這是一個(gè)Spring Swagger的配置文件。
之后,定義了一個(gè)Bean方法CustomDocket,Spring中名字并不重要,重要的是它返回一個(gè)Docket類,DocumentationType.SWAGGER_2作為Docket構(gòu)造方法的參數(shù),指定了所用的swagger版本2.0,官網(wǎng)上已經(jīng)在預(yù)告3.0版本了。而之后的apiInfo則是調(diào)用接下來的apiInfo函數(shù),來創(chuàng)建Docket的信息。apiInfo函數(shù)采用ApiInfoBuilder來創(chuàng)建ApiInfo類。
五、一個(gè)控制器
其實(shí),控制器不需要配置,就已經(jīng)會(huì)被springfox swagger識(shí)別了,不過我們這里象征性地加上一個(gè)描述信息:
@Controller @RequestMapping("/test") public class TestController { @ApiOperation(value="一個(gè)測試API",notes = "第一個(gè)測試api") @ResponseBody @RequestMapping(value = "/hello",method = RequestMethod.GET) public String hello() { return "hello"; } }
這里僅僅多了一個(gè)@ApiOperation注解,別的和一個(gè)普通的springmvc的控制器完全一致。
實(shí)際上,為了形成一個(gè)完整的api文檔,需要添加的注解常常很多,若是都寫在同一個(gè)文件里就會(huì)顯得臃腫,我們常常會(huì)寫一個(gè)接口文件,將注解都放在接口文件中,然后再用一個(gè)實(shí)體類來實(shí)現(xiàn)控制器,算是實(shí)現(xiàn)配置和邏輯分離了吧。
六、查看接口文件和文檔
若是沒有問題,現(xiàn)在可以部署項(xiàng)目,并打開http://localhost:8080/demo/v2/api-docs:
Firefox提供了查看JSON的插件,推薦大家搜索試試看。
廢話不多說,這里可以看到之前配置的諸多信息。注入description,version,title等。并且確實(shí)有TestController的信息。
最后,我們打開http://localhost:8080/swagger-ui.html,便可以看到一個(gè)漂亮的界面了:
以上這篇詳談Springfox與swagger的整合使用就是小編分享給大家的全部內(nèi)容了,希望能給大家一個(gè)參考,也希望大家多多支持億速云。
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場,如果涉及侵權(quán)請(qǐng)聯(lián)系站長郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。