前言
springBoot作為微服務(wù)首選框架，為其他服務(wù)提供大量的接口服務(wù)。接口對(duì)接方需要實(shí)時(shí)最近的接口文檔。
swagger可以通過(guò)代碼和注釋自動(dòng)為web項(xiàng)目生成在線(xiàn)文檔，這里使用swagger。
當(dāng) SpringBoot 代碼中 SpringMVC 使用自動(dòng)化配置類(lèi) WebMvcAutoConfiguration 時(shí)，其整合 Swagger2 的方法如下。
如果 SpringMVC 的配置過(guò)程使用了 WebMvcConfigurationSupport；則如下的整合方法不適合。
一、Spring Boot Web 整合 Swagger2 過(guò)程
Spring Boot Web 項(xiàng)目整合 Swagger2 主要有兩個(gè)過(guò)程：
- 添加 Swagger2 相關(guān)依賴(lài)。
- 配置 Swagger2 配置類(lèi)。
1.1、添加 Swagger2 相關(guān)依賴(lài)
首先要對(duì) Spring Boot Web 的項(xiàng)目，添加 Swagger2 相關(guān)的依賴(lài)：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <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> |
1.2、配置 Swagger2 配置類(lèi)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
@Configuration@EnableSwagger2public class Swagger { //創(chuàng)建 Docket 的Bean @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //select() 函數(shù)返回一個(gè) ApiSelectorBuilder實(shí)例用來(lái)控制哪些接口暴露給 Swagger 來(lái)展現(xiàn) .select() //要掃描的包 .apis(RequestHandlerSelectors.basePackage("com.example.controller")) //選擇API路徑 .paths(PathSelectors.any()) .build(); }? //創(chuàng)建文檔的基本信息 public ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("Swagger UI 的標(biāo)題") .description("用restful風(fēng)格寫(xiě)接口") .termsOfServiceUrl("") .version("1.0") .build(); }} |
二、配置 Swagger2 接口常用注解
2.1、@Api 請(qǐng)求類(lèi)說(shuō)明
寫(xiě)在controller類(lèi)定義上方,用于說(shuō)明類(lèi)的作用。
|
1
2
3
|
@Api(value = "Swagger Test Control", description = "演示Swagger用法的Control類(lèi)", tags = "Swagger Test Control Tag") |
2.2、@ApiOperation 方法的說(shuō)明
寫(xiě)在REST接口上方，用于說(shuō)明方法的作用。
|
1
2
3
|
@ApiOperation(value="創(chuàng)建用戶(hù)", notes="根據(jù)User對(duì)象創(chuàng)建用戶(hù)") |
2.3、@ApiImplicitParams 和 @ApiImplicitParam 方法參數(shù)說(shuō)明
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
@ApiImplicitParams：用在請(qǐng)求的方法上，包含一組參數(shù)說(shuō)明 @ApiImplicitParam：對(duì)單個(gè)參數(shù)的說(shuō)明 name：參數(shù)名 value：參數(shù)的漢字說(shuō)明、解釋 required：參數(shù)是否必須傳 paramType：參數(shù)放在哪個(gè)地方 · header --> 請(qǐng)求參數(shù)的獲取：@RequestHeader · query --> 請(qǐng)求參數(shù)的獲取：@RequestParam · path（用于restful接口）--> 請(qǐng)求參數(shù)的獲?。?/code> · body（請(qǐng)求體）--> @RequestBody User user · form（普通表單提交） dataType：參數(shù)類(lèi)型，默認(rèn)String，其它值dataType="int" defaultValue：參數(shù)的默認(rèn)值--------------------------------------------------------------------@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "ID", dataType = "Long"), @ApiImplicitParam(name = "user", value = "用戶(hù)", dataType = "User")}) |
2.4、@ApiResponses 和 @ApiResponse 方法返回值的說(shuō)明
|
1
2
3
4
5
6
7
8
9
10
|
@ApiResponses：方法返回對(duì)象的說(shuō)明 @ApiResponse：每個(gè)參數(shù)的說(shuō)明 code：數(shù)字，例如400 message：信息，例如"請(qǐng)求參數(shù)沒(méi)填好" response：拋出異常的類(lèi)-------------------------------------------------------------------@ApiResponses({ @ApiResponse(code = 400, message = "權(quán)限不足"), @ApiResponse(code = 500, message = "服務(wù)器內(nèi)部異常") }) |
2.5、@ApiModel 和 @ApiModelProperty
@ApiModel 用于JavaBean 上面，表示一個(gè)JavaBean。這種一般用在post創(chuàng)建的時(shí)候，使用 @RequestBody 這樣的場(chǎng)景，請(qǐng)求參數(shù)無(wú)法使用 @ApiImplicitParam 注解進(jìn)行描述的時(shí)候。
@ApiModelProperty 用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段。
|
1
2
3
4
5
6
7
8
9
|
@ApiModel( description = "學(xué)生")public class Student { @ApiModelProperty(value = "主鍵id") private String id; @ApiModelProperty(value = "名稱(chēng)", required = true) private String name; @ApiModelProperty(value = "年齡", required = true) private int age;} |
2.6、其他注解
@ApiIgnore ：使用該注解忽略這個(gè)API，不對(duì)這個(gè)接口生成文檔。
@ApiError：發(fā)生錯(cuò)誤返回的信息
總結(jié)
到此這篇關(guān)于SpringBoot整合Swagger2的文章就介紹到這了,更多相關(guān)SpringBoot整合Swagger2內(nèi)容請(qǐng)搜索服務(wù)器之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持服務(wù)器之家！
原文鏈接：https://cn-blogs.cn/archives/10205.html
