Spring boot 集成Swagger | Java提升营

Spring boot 集成Swagger

Swagger 是一个简单强大的 API 设计表达工具。它提供一套通过代码和注解自动生成文档的方法。当前主流编程语言都支持 Swagger。这里记录在 Spring boot 中使用 Swagger 记录。

添加依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- 自动生成描述 API 的 json 文件 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>

<!-- 将 json 文件解析出来,用一种更友好的方式呈现 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

配置参数

1
2
3
4
5
6
7
8
9
10
swagger:
title: API标题
description: API描述
version: 1.0.0
terms-of-service-url: http://blog.hxpgxt.cn
base-package: com.hxpgxt.blog
contact:
name: Noodles Mars
url: http://blog.hxpgxt.cn
email: noodlesMars@hxpgxt.cn

配置类

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
/**
* conf.SwaggerConfig.java
* @Configuration 告诉 Spring Boot 需要加载这个配置类
* @EnableSwagger2 启用 Swagger2
*/
@Configuration
@EnableSwagger2
@ConditionalOnClass(EnableSwagger2.class)
@Data
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

/**
* API页面标题
*/
private String title;

/**
* API描述
*/
private String description;

/**
* API版本号
*/
private String version;

/**
* API接口包路径
*/
private String basePackage;

/**
* 服务条款地址
*/
private String termsOfServiceUrl;

/**
* 联系人
*/
private Contact contact;

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.termsOfServiceUrl(termsOfServiceUrl)
.version(version)
.contact(contact)
.build();
}
}

使用

注解名称使用说明
@Api描述一个 API 类
@ApiImplicitParam描述一个请求参数
@ApiImplicitParams描述一组请求参数
@ApiModel描述一个返回的对象
@ApiModelProperty描述一个返回的对象参数
@ApiOperation描述一个 API 方法
@ApiParam描述一个方法的参数
@ApiResponse描述一个请求响应
@ApiResponses描述一组请求响应
@ApiIgnore表示忽略
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
31
32
33
34
@Api(tags = "买家商品", description = "买家商品相关 Rest API")
public class BuyerOrderController {
@ApiOperation(value="订单详情")
@ApiImplicitParams({
@ApiImplicitParam(name = "openid", value = "买家 openid", required = true, dataType = "String"),
@ApiImplicitParam(name = "orderId", value = "订单 ID", required = true, dataType = "String")
})
@GetMapping("/detail")
public ResultVO<OrderDTO> detail(
@RequestParam("openid") String openid,
@RequestParam("orderId") String orderId) {
OrderDTO orderDTO = buyerService.findOrderOne(openid, orderId);
return ResultVOUtil.success(orderDTO);
}
}
/**
* 商品信息
*/
@Data
@ApiModel("商品类目详情")
public class ProductVO {

@ApiModelProperty("类目名称")
@JsonProperty("name")
private String categoryName;

@ApiModelProperty("类目类型")
@JsonProperty("type")
private Integer categoryType;

@ApiModelProperty("商品列表")
@JsonProperty("list")
private List<ProductInfoVO> productInfoVOList;
}

启动项目访问路径查看文档:http://ip:port/swagger-ui.html

给老奴加个鸡腿吧 🍨.