Java Swagger使用教程
Swagger簡介
為什么使用Swagger
這個問題就牽涉到技術(shù)的更新迭代了,在之前的后端時代,前端只需要管理靜態(tài)頁面,而后端需要使用模板引擎(JSP等)去得數(shù)據(jù)并加以處理,最后顯示出數(shù)據(jù)。但是隨著時代的發(fā)展,開發(fā)慢慢進(jìn)入了前后端分離的時代,前端和后端分成了兩個相對獨立的團(tuán)隊來合作開發(fā),這就造成了一個問題:前后端集成聯(lián)調(diào)的時候,前后端人員無法做到“及時協(xié)商,盡早解決”,最終造成問題的集中爆發(fā)。
既然已經(jīng)發(fā)現(xiàn)問題,那么就需要使用一種解決方案來避免這個問題的干擾。做過一個完整項目的小伙伴應(yīng)該都有所了解,前后端之間的協(xié)作基本上都在api接口和數(shù)據(jù)傳輸上,那么如果api接口能夠統(tǒng)一、數(shù)據(jù)的格式能夠一致,那么問題也就迎刃而解了。
于是Swagger應(yīng)運而生,Swagger可以根據(jù)在代碼中使用自定義的注解來生成接口文檔,這樣做的好處是在開發(fā)接口時可以通過swagger將接口文檔定義好,方便前后端團(tuán)隊之間的協(xié)作,同時也方便以后的維護(hù)。
Swagger的配置
Spring boot集成Swagger
新建一個spring boot項目
導(dǎo)入兩個依賴
<!--Swagger(開始)--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!--Swagger(結(jié)束)-->
配置Swagger
@Configuration @EnableSwagger2 // 開啟Swagger2 public class SwaggerConfig { }
如果只是使用配置類開啟Swagger的話,它的底層會有一些DEFAULT(默認(rèn))的值,開啟之后就可以使用網(wǎng)址http://localhost:8080/swagger-ui.html來訪問這個Swagger的文檔界面。
當(dāng)然,既然有默認(rèn)的配置,我們就可以實現(xiàn)定制化的配置覆蓋,依然是在這個配置類中進(jìn)行修改
@Configuration @EnableSwagger2 // 開啟Swagger2 public class SwaggerConfig { /** *用于定制化配置Docket的bean實例 */ @Bean public Docket Docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(ApiInfo()); } /** * 定制化信息的主要設(shè)置處 */ private ApiInfo ApiInfo() { // 作者的個人信息 Contact contact = new Contact("作者的姓名", "作者的個人社交主頁", "作者的郵箱"); return new ApiInfo( "標(biāo)題:Swagger的測試接口文檔", "簡介:這是一段簡介,關(guān)于接口文檔的簡介", "版本號:1.0", "網(wǎng)頁:這是一個網(wǎng)頁鏈接", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<>() ); } }
修改之后的頁面信息就會有一些不一樣,restart項目之后重新訪問ui界面
配置Swagger可掃描的接口
這一部分的工作也是在SwaggerConfig配置類中實現(xiàn),主要就是配置哪些api接口會被Swagger生成接口文檔,生成文檔的api就會在swagger的ui界面上顯示。通過以下.apis和.paths的配置,達(dá)到的效果就是之后在com.xiaochen.swagger.controller包下的且映射路徑為/hello的才會生成對應(yīng)的接口文檔
@Bean public Docket Docket() { return new Docket(DocumentationType.SWAGGER_2) .select() /** * apis就是配置哪些api可以被掃描 * 主要參數(shù)可以包括: * - RequestHandlerSelectors.basePackage():指定可以掃描的包 參數(shù)是包(package)名 * - RequestHandlerSelectors.any():掃描所有 * - RequestHandlerSelectors.none():都不掃描 * - RequestHandlerSelectors.withClassAnnotation():掃描類上注解 參數(shù)是注解類的反射對象,eg:@RestController.class * - RequestHandlerSelectors.withMethodAnnotation()掃描方法上注解 參數(shù)是注解類的反射對象,eg:@RequestMapping.class */ .apis(RequestHandlerSelectors.basePackage("com.xiaochen.swagger.controller")) /** * paths就是配置哪些映射路徑下的api可以被掃描 * 主要參數(shù)可以包括: * - PathSelectors.ant():指定映射路徑 主要就是斜杠+單詞或者通配符 * - PathSelectors.any():掃描所有 * - PathSelectors.none():都不掃描 * - PathSelectors.regex():掃描符合正則的所有路徑 */ .paths(PathSelectors.ant("/hello")) .build() .apiInfo(ApiInfo()); }
控制Swagger的開關(guān)
使用.enable可以控制Swagger的開關(guān),如果關(guān)閉了Swagger的話就會導(dǎo)致ui界面無法打開,也就無法查看接口文檔
那么該如何實現(xiàn)只在開發(fā)和測試階段開啟Swagger呢?首先應(yīng)該先預(yù)設(shè)一下想要開啟的項目環(huán)境,通過Environment 對象來監(jiān)聽項目的環(huán)境與預(yù)設(shè)的是否一致,最后使用.enable控制Swagger的開關(guān)
@Bean public Docket Docket(Environment environment) { // 預(yù)設(shè)的項目環(huán)境(可設(shè)置多個) Profiles profiles = Profiles.of("dev", "test"); // 監(jiān)聽項目的環(huán)境與預(yù)設(shè)的是否一致 boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .enable(flag); }
設(shè)置Swagger的分組
在沒有設(shè)置Swagger的分組之前,有一個默認(rèn)的default分組,分組個數(shù)的多少就取決于SwaggerConfig 配置類中有多少個Docket 實例,值得注意的是:不能出現(xiàn)同名的分組,即使是未命名的分組(也就是default)也不能重復(fù)出現(xiàn),否則就會報java.lang.IllegalStateException異常
Swagger的各種注釋
controller層使用到的注解
- @ApiOperation(“注釋”):加在方法上,注釋這個方法
- @ApiParam(“注釋”):加在參數(shù)前,注釋這個參數(shù)
entity層使用到的注解
- @ApiModel(“注釋”):加在實體類上,注釋整個實體類
- @ApiModelProperty(“注釋”):加在實體類字段上,注釋這個字段
model里面是否有這個實體類,并不是取決于是否使用了哪個注解,而是方法的返回值是否包含這個實體類對象,也就是看有沒有一個方法return了這個對象。
使用Swagger接口測試
這里的使用和postman幾乎一樣,可以借鑒學(xué)習(xí)
到此這篇關(guān)于Java Swagger使用教程的文章就介紹到這了,更多相關(guān)Java Swagger內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
對Java ArrayList的自動擴(kuò)容機制示例講解
今天小編就為大家分享一篇對Java ArrayList的自動擴(kuò)容機制示例講解,具有很好的參考價值,希望對大家有所幫助。一起跟隨小編過來看看吧2018-10-10Java多線程編程中使用Condition類操作鎖的方法詳解
Condition是java.util.concurrent.locks包下的類,提供了對線程鎖的更精細(xì)的控制方法,下面我們就來看一下Java多線程編程中使用Condition類操作鎖的方法詳解2016-07-07Spring MVC數(shù)據(jù)處理和亂碼問題詳解
這篇文章主要給大家介紹了關(guān)于Spring MVC數(shù)據(jù)處理和亂碼問題的相關(guān)資料,文中通過示例代碼介紹的非常詳細(xì),對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2020-12-12SpringMVC九大組件之HandlerMapping詳解
這篇文章主要介紹了SpringMVC九大組件之HandlerMapping詳解,HandlerMapping 叫做處理器映射器,它的作用就是根據(jù)當(dāng)前 request 找到對應(yīng)的 Handler 和 Interceptor,然后封裝成一個 HandlerExecutionChain 對象返回,需要的朋友可以參考下2023-09-09基于SpringIOC創(chuàng)建對象的四種方式總結(jié)
這篇文章主要介紹了基于SpringIOC創(chuàng)建對象的四種方式總結(jié),具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教2021-06-06基于SpringBoot與Mybatis實現(xiàn)SpringMVC Web項目
這篇文章主要介紹了基于SpringBoot與Mybatis實現(xiàn)SpringMVC Web項目的相關(guān)資料,需要的朋友可以參考下2017-04-04解讀SpringBoot接收List<Bean>參數(shù)問題(POST請求方式)
這篇文章主要介紹了解讀SpringBoot接收List<Bean>參數(shù)問題(POST請求方式),具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教2022-09-09Retrofit+Rxjava下載文件進(jìn)度的實現(xiàn)
這篇文章主要介紹了Retrofit+Rxjava下載文件進(jìn)度的實現(xiàn),非常不錯,具有參考借鑒價值,需要的朋友可以參考下2017-11-11springboot cloud使用eureka整合分布式事務(wù)組件Seata 的方法
這篇文章主要介紹了springboot cloud使用eureka整合分布式事務(wù)組件Seata 的方法 ,本文給大家介紹的非常詳細(xì),對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值,需要的朋友可以參考下2021-05-05Java靜態(tài)static與實例instance方法示例
這篇文章主要為大家介紹了Java靜態(tài)static與實例instance方法示例,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進(jìn)步,早日升職加薪2023-08-08