Spring boot 集成Swagger | Java提升营

Java提升营

探索编程的乐趣

Spring boot 集成Swagger

原创 | 发表于 更新于 分类于 ， Valine： 3.1k 3 分钟

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

给老奴加个鸡腿吧 🍨.