Spring Boot 集成 Swagger2 构建 RESTful API 文档

Posted by 彭超 on 2019-07-28
Estimated Reading Time 2 Minutes
Words 526 In Total
Viewed Times

引入依赖

pom.xml 中添加 io.springfox:springfox-swagger2io.springfox:springfox-swagger-ui 依赖

1
2
3
4
5
6
7
8
9
10
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>

相关配置

创建 Swagger2Config 配置类

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
27
28
29
30
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;

@Configuration
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("{Controler 扫描路径}"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("{标题}")
.description("{描述}")
.termsOfServiceUrl("{网址}")
.version("{版本号}")
.build();
}
}

注意:需要在 RequestHandlerSelectors.basePackage 参数中设置 Controller 包路径,否则生成的文档扫描不到接口。

Application 中添加 @EnableSwagger2 注解

1
2
3
4
5
6
7
@EnableSwagger2
@SpringBootApplication
public class ServiceAdminApplication {
public static void main(String[] args) {
SpringApplication.run(ServiceAdminApplication.class, args);
}
}

使用 Swagger2

Controller 中的请求接口里加入以下常用 Swagger 注解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@RestController
@RequestMapping(value = "/api/v2/user")
@Api(tags = "用户管理")
public class UserController() {

@ApiOperation(value = "分页查询用户列表")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int", paramType = "path"),
@ApiImplicitParam(name = "pageSize", value = "页数", required = true, dataType = "int", paramType = "path"),
@ApiImplicitParam(name = "UserJson", value = "对象 JSON 字符串", required = false, dataTypeClass = String.class, paramType = "json")
})
@RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
public BaseResult page(
@PathVariable(required = true) int pageNum,
@PathVariable(required = true) int pageSize,
@RequestParam(required = false) String UserJson
){
return null;
}
}

Swagger 注解使用说明

  • @Api:修饰整个类,描述 Controller 的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiImplicitParam:一个请求参数
  • @ApiImplicitParams:多个请求参数
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponseHTTP 响应其中 1 个描述
  • @ApiResponsesHTTP 响应整体描述
  • @ApiIgnore:使用该注解忽略这个 API
  • @ApiError:发生错误返回的信息

启动项目,访问 Swagger 地址:http://{ip}:{port}/swagger-ui.html


If you like this blog or find it useful for you, you are welcome to comment on it. You are also welcome to share this blog, so that more people can participate in it. If the images used in the blog infringe your copyright, please contact the author to delete them. Thank you !