Spring Boot整合swagger使用教程詳解
Swagger的介紹
🔶你可能嘗試過寫完一個接口后,自己去創(chuàng)建接口文檔,或者修改接口后修改接口文檔。多了之后,你肯定會發(fā)生一個操作,那就是忘記了修改文檔或者創(chuàng)建文檔(除非你們公司把接口文檔和寫接口要求得很緊密😓忘記寫文檔就扣工資?,否則兩個分離的工作總是有可能遺漏的)。而swagger就是一個在你寫接口的時候自動幫你生成接口文檔的東西,只要你遵循它的規(guī)范并寫一些接口的說明注解即可。
優(yōu)點與缺點
🔶優(yōu)點:
- 自動生成文檔,只需要在接口中使用注解進行標(biāo)注,就能生成對應(yīng)的接口文檔。
- 自動更新文檔,由于是動態(tài)生成的,所以如果你修改了接口,文檔也會自動對應(yīng)修改(如果你也更新了注解的話)。這樣就不會發(fā)送我修改了接口,卻忘記更新接口文檔的情況。
- 支持在線調(diào)試,swagger提供了在線調(diào)用接口的功能。
🔶缺點:
- 不能創(chuàng)建測試用例,所以他暫時不能幫你處理完所有的事情。他只能提供一個簡單的在線調(diào)試,如果你想存儲你的測試用例,可以使用Postman或者YAPI這樣支持創(chuàng)建測試用戶的功能。
- 要遵循一些規(guī)范,它不是任意規(guī)范的。比如說,你可能會返回一個json數(shù)據(jù),而這個數(shù)據(jù)可能是一個Map格式的,那么我們此時不能標(biāo)注這個Map格式的返回數(shù)據(jù)的每個字段的說明,而如果它是一個實體類的話,我們可以通過標(biāo)注類的屬性來給返回字段加說明。也比如說,對于swagger,不推薦在使用GET方式提交數(shù)據(jù)的時候還使用Body,僅推薦使用query參數(shù)、header參數(shù)或者路徑參數(shù),當(dāng)然了這個限制只適用于在線調(diào)試。
- 沒有接口文檔更新管理,雖然一個接口更新之后,可能不會關(guān)心舊版的接口信息,但你“可能”想看看舊版的接口信息,例如有些灰度更新發(fā)布的時候可能還會關(guān)心舊版的接口。那么此時只能由后端去看看有沒有注釋留下了,所以可以考慮接口文檔大更新的時候注釋舊版的,然后寫下新版的?!井?dāng)然這個問題可以通過導(dǎo)出接口文檔來對比?!?/li>
- 雖然現(xiàn)在Java的實體類中有不少模型,po,dto,vo等,模型的區(qū)分是為了屏蔽一些多余參數(shù),比如一個用戶登錄的時候只需要username,password,但查權(quán)限的時候需要連接上權(quán)限表的信息,而如果上述兩個操作都是使用了User這個實體的話,在文檔中就會自動生成了多余的信息,這就要求了你基于模型來創(chuàng)建多個實體類,比如登錄的時候一個LoginForm,需要用戶-權(quán)限等信息的時候才使用User類。(當(dāng)然了,這個問題等你會swagger之后你就大概就會怎么規(guī)避這個問題了。)
😓上面的缺點好像寫的有點多,你可能會覺得swagger這個坑有點大。但其實主要是規(guī)范問題,而規(guī)范問題有時候又會提高你的代碼規(guī)范性,這個就見仁見智了,你以前可能什么接口的參數(shù)都使用一個類,而現(xiàn)在swagger要求你分開后,某種層次上提高了你的代碼規(guī)范性。
🔶注:以下代碼示例基于Spring Boot。完整代碼可以參考:swagger-demo
添加swagger
💡這里先講添加swagger,也就是先整合進來,至于怎么使用,下面的“場景”中再講解。
1.添加依賴包:
❗注意,這里的前提是已經(jīng)導(dǎo)入了spring boot的web包。
<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>
2.配置Swagger:
要使用swagger,我們必須對swagger進行配置,我們需要創(chuàng)建一個swagger的配置類,比如可以命名為SwaggerConfig.java
package com.example.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration // 標(biāo)明是配置類 @EnableSwagger2 //開啟swagger功能 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的,代表swagger2 // .groupName("分布式任務(wù)系統(tǒng)") // 如果配置多個文檔的時候,那么需要配置groupName來分組標(biāo)識 .apiInfo(apiInfo()) // 用于生成API信息 .select() // select()函數(shù)返回一個ApiSelectorBuilder實例,用來控制接口被swagger做成文檔 .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定掃描哪個包下的接口 .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔,可以配置這里 .build(); } /** * 用于定義API主界面的信息,比如可以聲明所有的API的總標(biāo)題、描述、版本 * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("XX項目API") // 可以用來自定義API的主標(biāo)題 .description("XX項目SwaggerAPI管理") // 可以用來描述整體的API .termsOfServiceUrl("") // 用于定義服務(wù)的域名 .version("1.0") // 可以用來定義版本。 .build(); // } }
3.測試
運行我們的Spring Boot項目,(我默認(rèn)是8080端口,如果你不一樣,請注意修改后續(xù)的url),訪問http://localhost:8080/swagger-ui.html
然后你就可以看到一個如下的界面,由于我們暫時沒有配置接口數(shù)據(jù),所以下面顯示No operations defined in spec!
💡下面我們將介紹如何定義接口,以及在swagger UI界面中的內(nèi)容。
場景:
定義接口組
接口有時候應(yīng)該是分組的,而且大部分都是在一個controller中的,比如用戶管理相關(guān)的接口應(yīng)該都在UserController中,那么不同的業(yè)務(wù)的時候,應(yīng)該定義/劃分不同的接口組。接口組可以使用@Api
來劃分。
比如:
@Api(tags = "角色管理") // tags:你可以當(dāng)作是這個組的名字。 @RestController public class RoleController { }
和
@Api(tags = "用戶管理") // tags:你可以當(dāng)作是這個組的名字。 @RestController public class UserController { }
🔵你也可以理解成基于tags來分組,就好像一些文章里面的標(biāo)簽一樣,使用標(biāo)簽來分類。
🔵如果這個Controller下(接口組)下面沒有接口,那么在swagger ui中是不會顯示的,如果有的話就會這樣顯示:
定義接口
使用了@Api
來標(biāo)注一個Controller之后,如果下面有接口,那么就會默認(rèn)生成文檔,但沒有我們自定義的說明:
@Api(tags = "用戶管理") @RestController public class UserController { // 注意,對于swagger,不要使用@RequestMapping, // 因為@RequestMapping支持任意請求方式,swagger會為這個接口生成7種請求方式的接口文檔 @GetMapping("/info") public String info(String id){ return "aaa"; } }
我們可以使用@ApiOperation
來描述接口,比如:
@ApiOperation(value = "用戶測試",notes = "用戶測試notes") @GetMapping("/test") public String test(String id){ return "test"; }
常用配置項:
- value:可以當(dāng)作是接口的簡稱notes:接口的描述
- tags:可以額外定義接口組,比如這個接口外層已經(jīng)有
@Api(tags = "用戶管理")
,將接口劃分到了“用戶管理”中,但你可以額外的使用 - tags,例如
tags = "角色管理"
讓角色管理中也有這個接口文檔。
定義接口請求參數(shù)
上面使用了@ApiOperation
來了描述接口,但其實還缺少接口請求參數(shù)的說明,下面我們分場景來講。
🔵注意一下,對于GET方式,swagger不推薦使用body方式來傳遞數(shù)據(jù),也就是不希望在GET方式時使用json、form-data等方式來傳遞,這時候最好使用路徑參數(shù)或者url參數(shù)。(😓雖然POSTMAN等是支持的),所以如果接口傳遞的數(shù)據(jù)是json或者form-data方式的,還是使用POST方式好。
場景一:請求參數(shù)是實體類。
此時我們需要使用@ApiModel
來標(biāo)注實體類,然后在接口中定義入?yún)閷嶓w類即可:
@ApiModel:用來標(biāo)類
常用配置項:
value:實體類簡稱
description:實體類說明
@ApiModelProperty:用來描述類的字段的意義。
常用配置項:
value:字段說明
example:設(shè)置請求示例(Example Value)的默認(rèn)值,如果不配置,當(dāng)字段為string的時候,此時請求示例中默認(rèn)值為"".name:用新的字段名來替代舊的字段名。
allowableValues:限制值得范圍,例如{1,2,3}
代表只能取這三個值;[1,5]
代表取1到5的值;(1,5)
代表1到5的值,不包括1和5;還可以使用infinity或-infinity來無限值,比如[1, infinity]
代表最小值為1,最大值無窮大。
required:標(biāo)記字段是否必填,默認(rèn)是false,
hidden:用來隱藏字段,默認(rèn)是false,如果要隱藏需要使用true,因為字段默認(rèn)都會顯示,就算沒有@ApiModelProperty
。
// 先使用@ApiModel來標(biāo)注類 @ApiModel(value="用戶登錄表單對象",description="用戶登錄表單對象") public class LoginForm { // 使用ApiModelProperty來標(biāo)注字段屬性。 @ApiModelProperty(value = "用戶名",required = true,example = "root") private String username; @ApiModelProperty(value = "密碼",required = true,example = "123456") private String password; // 此處省略入?yún)①x值時需要的getter,setter,swagger也需要這個 }
定義成入?yún)ⅲ?/p>
@ApiOperation(value = "登錄接口",notes = "登錄接口的說明") @PostMapping("/login") public LoginForm login(@RequestBody LoginForm loginForm){ return loginForm; }
效果:
場景二:請求參數(shù)是非實體類。
(再說一次:對于GET方式,swagger不推薦使用body方式來傳遞數(shù)據(jù),所以雖然Spring MVC可以自動封裝參數(shù),但對于GET請求還是不要使用form-data,json等方式傳遞參數(shù),除非你使用Postman來測試接口,swagger在線測試是不支持這個操作的)
對于非實體類參數(shù),可以使用@ApiImplicitParams
和@ApiImplicitParam
來聲明請求參數(shù)。
@ApiImplicitParams
用在方法頭上,@ApiImplicitParam
定義在@ApiImplicitParams
里面,一個@ApiImplicitParam
對應(yīng)一個參數(shù)。
@ApiImplicitParam
常用配置項:
- name:用來定義參數(shù)的名字,也就是字段的名字,可以與接口的入?yún)⒚麑?yīng)。如果不對應(yīng),也會生成,所以可以用來定義額外參數(shù)!
- value:用來描述參數(shù)
- required:用來標(biāo)注參數(shù)是否必填
- paramType有path,query,body,form,header等方式,但對于對于非實體類參數(shù)的時候,常用的只有path,query,header;body和form是不常用的。body不適用于多個零散參數(shù)的情況,只適用于json對象等情況?!救绻愕慕涌谑?code>form-data,
x-www-form-urlencoded
的時候可能不能使用swagger頁面API調(diào)試,但可以在后面講到基于BootstrapUI的swagger增強中調(diào)試,基于BootstrapUI的swagger支持指定form-data
或x-www-form-urlencoded
】
示例一:聲明入?yún)⑹荱RL參數(shù)
// 使用URL query參數(shù) @ApiOperation(value = "登錄接口2",notes = "登錄接口的說明2") @ApiImplicitParams({ @ApiImplicitParam(name = "username",//參數(shù)名字 value = "用戶名",//參數(shù)的描述 required = true,//是否必須傳入 //paramType定義參數(shù)傳遞類型:有path,query,body,form,header paramType = "query" ) , @ApiImplicitParam(name = "password",//參數(shù)名字 value = "密碼",//參數(shù)的描述 required = true,//是否必須傳入 paramType = "query" ) }) @PostMapping(value = "/login2") public LoginForm login2(String username,String password){ System.out.println(username+":"+password); LoginForm loginForm = new LoginForm(); loginForm.setUsername(username); loginForm.setPassword(password); return loginForm; }
示例二:聲明入?yún)⑹荱RL路徑參數(shù)
// 使用路徑參數(shù) @PostMapping("/login3/{id1}/{id2}") @ApiOperation(value = "登錄接口3",notes = "登錄接口的說明3") @ApiImplicitParams({ @ApiImplicitParam(name = "id1",//參數(shù)名字 value = "用戶名",//參數(shù)的描述 required = true,//是否必須傳入 //paramType定義參數(shù)傳遞類型:有path,query,body,form,header paramType = "path" ) , @ApiImplicitParam(name = "id2",//參數(shù)名字 value = "密碼",//參數(shù)的描述 required = true,//是否必須傳入 paramType = "path" ) }) public String login3(@PathVariable Integer id1,@PathVariable Integer id2){ return id1+":"+id2; }
示例三:聲明入?yún)⑹莌eader參數(shù)
// 用header傳遞參數(shù) @PostMapping("/login4") @ApiOperation(value = "登錄接口4",notes = "登錄接口的說明4") @ApiImplicitParams({ @ApiImplicitParam(name = "username",//參數(shù)名字 value = "用戶名",//參數(shù)的描述 required = true,//是否必須傳入 //paramType定義參數(shù)傳遞類型:有path,query,body,form,header paramType = "header" ) , @ApiImplicitParam(name = "password",//參數(shù)名字 value = "密碼",//參數(shù)的描述 required = true,//是否必須傳入 paramType = "header" ) }) public String login4( @RequestHeader String username, @RequestHeader String password){ return username+":"+password; }
示例四:聲明文件上傳參數(shù)
// 有文件上傳時要用@ApiParam,用法基本與@ApiImplicitParam一樣,不過@ApiParam用在參數(shù)上 // 或者你也可以不注解,swagger會自動生成說明 @ApiOperation(value = "上傳文件",notes = "上傳文件") @PostMapping(value = "/upload") public String upload(@ApiParam(value = "圖片文件", required = true)MultipartFile uploadFile){ String originalFilename = uploadFile.getOriginalFilename(); return originalFilename; } // 多個文件上傳時,**swagger只能測試單文件上傳** @ApiOperation(value = "上傳多個文件",notes = "上傳多個文件") @PostMapping(value = "/upload2",consumes = "multipart/*", headers = "content-type=multipart/form-data") public String upload2(@ApiParam(value = "圖片文件", required = true,allowMultiple = true)MultipartFile[] uploadFile){ StringBuffer sb = new StringBuffer(); for (int i = 0; i < uploadFile.length; i++) { System.out.println(uploadFile[i].getOriginalFilename()); sb.append(uploadFile[i].getOriginalFilename()); sb.append(","); } return sb.toString(); } // 既有文件,又有參數(shù) @ApiOperation(value = "既有文件,又有參數(shù)",notes = "既有文件,又有參數(shù)") @PostMapping(value = "/upload3") @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "圖片新名字", required = true ) }) public String upload3(@ApiParam(value = "圖片文件", required = true)MultipartFile uploadFile, String name){ String originalFilename = uploadFile.getOriginalFilename(); return originalFilename+":"+name; }
定義接口響應(yīng)
定義接口響應(yīng),是方便查看接口文檔的人能夠知道接口返回的數(shù)據(jù)的意義。
響應(yīng)是實體類:
前面在定義接口請求參數(shù)的時候有提到使用@ApiModel
來標(biāo)注類,如果接口返回了這個類,那么這個類上的說明也會作為響應(yīng)的說明:
// 返回被@ApiModel標(biāo)注的類對象 @ApiOperation(value = "實體類響應(yīng)",notes = "返回數(shù)據(jù)為實體類的接口") @PostMapping("/role1") public LoginForm role1(@RequestBody LoginForm loginForm){ return loginForm; }
響應(yīng)是非實體類:
swagger無法對非實體類的響應(yīng)進行詳細(xì)說明,只能標(biāo)注響應(yīng)碼等信息。是通過@ApiResponses
和@ApiResponse
來實現(xiàn)的。
@ApiResponses
和@ApiResponse
可以與@ApiModel
一起使用。
// 其他類型的,此時不能增加字段注釋,所以其實swagger推薦使用實體類 @ApiOperation(value = "非實體類",notes = "非實體類") @ApiResponses({ @ApiResponse(code=200,message = "調(diào)用成功"), @ApiResponse(code=401,message = "無權(quán)限" ) } ) @PostMapping("/role2") public String role2(){ return " {\n" + " name:\"廣東\",\n" + " citys:{\n" + " city:[\"廣州\",\"深圳\",\"珠海\"]\n" + " }\n" + " }"; }
Swagger UI增強
你可能會覺得現(xiàn)在這個UI不是很好看,現(xiàn)在有一些第三方提供了一些Swagger UI增強,比較流行的是swagger-bootstrap-ui
,我們這里以swagger-bootstrap-ui
為例。
UI對比:
使用
1.添加依賴包:
<!--引入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-bootstrap-ui依賴包--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.8.7</version> </dependency>
2.在swagger配置類中增加注解@EnableSwaggerBootstrapUI
:
@Configuration // 標(biāo)明是配置類 @EnableSwagger2 //開啟swagger功能 @EnableSwaggerBootstrapUI // 開啟SwaggerBootstrapUI public class SwaggerConfig { // 省略配置內(nèi)容 }
3.訪問API:http://localhost:8080/doc.html
,即可預(yù)覽到基于bootstarp的Swagger UI界面。
優(yōu)點
1.🤔界面好看了一點
2.上面說過了,基于BootstrapUI的swagger支持指定form-data
或x-www-form-urlencoded
:
3.支持復(fù)制單個API文檔和導(dǎo)出全部API文檔:
整合Spring Security注意
在Spring Boot整合Spring Security和Swagger的時候,需要配置攔截的路徑和放行的路徑,注意是放行以下幾個路徑。
.antMatchers("/swagger**/**").permitAll() .antMatchers("/webjars/**").permitAll() .antMatchers("/v2/**").permitAll() .antMatchers("/doc.html").permitAll() // 如果你用了bootstarp的Swagger UI界面,加一個這個。
對于token的處理
在swagger中只支持了簡單的調(diào)試,但對于一些接口,我們測試的時候可能需要把token信息寫到header中,目前好像沒看到可以自定義加請求頭的地方?
💡方法一:
如果你使用了Swagger BootstrapUI,那么你可以在“文檔管理”中增加全局參數(shù),這包括了添加header參數(shù)。
💡方法二:在swagger配置類中增加全局參數(shù)配置:
//如果有額外的全局參數(shù),比如說請求頭參數(shù),可以這樣添加 ParameterBuilder parameterBuilder = new ParameterBuilder(); List<Parameter> parameters = new ArrayList<Parameter>(); parameterBuilder.name("authorization").description("令牌") .modelRef(new ModelRef("string")).parameterType("header").required(false).build(); parameters.add(parameterBuilder.build()); return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的,代表swagger2 .apiInfo(apiInfo()) // 用于生成API信息 .select() // select()函數(shù)返回一個ApiSelectorBuilder實例,用來控制接口被swagger做成文檔 .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定掃描哪個包下的接口 .paths(PathSelectors.any())// 選擇所有的API,如果你想只為部分API生成文檔,可以配置這里 .build().globalOperationParameters(parameters);
💡方法三:使用@ApiImplicitParams
來額外標(biāo)注一個請求頭參數(shù),例如:
// 如果需要額外的參數(shù),非本方法用到,但過濾器要用,類似于權(quán)限token @PostMapping("/login6") @ApiOperation(value = "帶token的接口",notes = "帶token的接口") @ApiImplicitParams({ @ApiImplicitParam(name = "authorization",//參數(shù)名字 value = "授權(quán)token",//參數(shù)的描述 required = true,//是否必須傳入 paramType = "header" ) , @ApiImplicitParam(name = "username",//參數(shù)名字 value = "用戶名",//參數(shù)的描述 required = true,//是否必須傳入 paramType = "query" ) }) public String login6(String username){ return username; }
Swagger的安全管理
1.如果你整合了權(quán)限管理,可以給swagger加上權(quán)限管理,要求訪問swagger頁面輸入用戶名和密碼,這些是spring security和shiro的事了,這里不講。
2.如果你僅僅是不想在正式環(huán)境中可以訪問,可以在正式環(huán)境中關(guān)閉Swagger自動配置,這就不會有swagger頁面了。使用@Profile({"dev","test"})
注解來限制只在dev或者test下啟用Swagger自動配置。
然后在Spring Boot配置文件中修改當(dāng)前profilespring.profiles.active=release
,重啟之后,此時無法訪問http://localhost:8080/swagger-ui.html
到此這篇關(guān)于Spring Boot整合swagger使用教程的文章就介紹到這了,更多相關(guān)Spring Boot整合swagger內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
SpringBoot實現(xiàn)前端驗證碼圖片生成和校驗
這篇文章主要為大家詳細(xì)介紹了SpringBoot實現(xiàn)前端驗證碼圖片生成和校驗,具有一定的參考價值,感興趣的小伙伴們可以參考一下2018-02-02實例解決Java異常之OutOfMemoryError的問題
在本篇文章中,我們給大家分享了關(guān)于解決Java異常之OutOfMemoryError的問題的方法,有此需要的朋友們學(xué)習(xí)下。2019-02-02Java中Spring技巧之?dāng)U展點的應(yīng)用
這篇文章主要介紹了Java中Spring技巧之?dāng)U展點的應(yīng)用,下文Spring容器的啟動流程圖展開其內(nèi)容的相關(guān)資料,具有一定的參考價值,需要的小伙伴可以參考一下2022-04-04Java8?CompletableFuture?異步多線程的實現(xiàn)
本文主要介紹了Java8?CompletableFuture?異步多線程的實現(xiàn),文中通過示例代碼介紹的非常詳細(xì),對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2023-04-04java 根據(jù)經(jīng)緯度獲取地址實現(xiàn)代碼
這篇文章主要介紹了 java 根據(jù)經(jīng)緯度獲取地址實現(xiàn)代碼的相關(guān)資料,需要的朋友可以參考下2017-05-05java 靜態(tài)工廠代替多參構(gòu)造器的適用情況與優(yōu)劣
這篇文章主要介紹了java 靜態(tài)工廠代替多參構(gòu)造器的優(yōu)劣,幫助大家更好的理解和使用靜態(tài)工廠方法,感興趣的朋友可以了解下2020-12-12