炸毛的猫
0%

Swagger3-Note

发表于 更新于 分类于

Swagger + knife 配置
在学习Mall项目中，用到了Swagger2对项目接口进行页面展示及测试，Swagger3可以进行插件增强，所以进行了升级

Swagger3

配置

依赖

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
<!--Swagger3.0-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
    <exclusions>
        <exclusion>
            <!--Swagger3 swagger-models降级-->
            <!--Swagger3  @ApiModelProperty 需要required以及example参数-->
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>
<!--增强插件-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

配置类

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
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
package com.yancy0109.mall.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


/**
 * Swagger3API文档配置类
 */
@EnableKnife4j
@Configuration
@EnableOpenApi
public class Swagger3Config {

    //Swagger3.0 注入Docket Bean实例
    @Bean
    public Docket docket(Environment environment){
        //配置要设置的Swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles比对是否属于开启Swagger的环境
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) //配置Swagger方法
                .enable(flag)       //是否启用swagger
                /**
                 * 一个Docket对应了一个组 可以同归配置多个Docket实例 来分管不同组
                 */
                .groupName("Mall电商")
                .select()
                /**
                 * apis():指定扫描的接口
                 * RequestHandlerSelectors:配置扫描接口的方式
                 *          basePackage:指定扫描的包
                 *          any:全面扫描
                 *          none:不扫描
                 *          withClassAnnotation:扫描类上的注解-Api.class
                 *          withMethodAnnotation:扫描方法上的的注解-ApiOperation.class
                 */
                //指定生成API的Controller包
                .apis(RequestHandlerSelectors.basePackage("com.yancy0109.mall.controller"))
                //为有@Api注解的Controller生成API文档
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                /**
                 * path():过滤路径
                 * PathSelectors:配置过滤的路径
                 *      any:不过滤全部路径？
                 *      none:过滤全部路径？
                 *      ant:过滤指定路径---按照Spring AntPathMatcher提供的match方法进行匹配
                 *      regex:过滤指定路径:按照String的matches方法进行匹配
                 */
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 配置Swagger信息
     * @return
     */
    private ApiInfo apiInfo(){
        //联系信息
        Contact contact = new Contact("yancy0109", "https://yancy0109.github.io/", "1156729237@qq.com");
        return new ApiInfoBuilder()
                .title("Swagger-UI")
                .description("Mall-Learing")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

配置类说明

对启用模式设置补充说明

我们的项目中并不会在上线项目继续开启Swagger，而在Swagger Docket注入时，可以配置是否启用

1
2
3
4
//配置要设置的Swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles比对是否属于开启Swagger的环境
boolean flag = environment.acceptsProfiles(profiles);

flag值及项目运行环境是否为Swagger环境

环境设置

这部分是对yaml配置进行补充,application.yaml可以开启指定配置,格式为application-xxx.yaml,引用时以逗号分隔

application.yaml

1
2
3
4
spring:
  #配置运行环境
  profiles:
    active: dev

application-dev.yaml

1
2
server:
  port: 8080

application-pro.yaml

1
2
server:
  port: 8080

使用

注解

接口注解

@Api()
  • tags Controller注解
@ApiOperation()
  • values Controller方法注解

实例

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
/**
 * 品牌管理Controller
 */
@Api(tags = "PmsBrandController")
@RestController
@RequestMapping("/brand")
public class PmsBrandController {

    @Autowired
    PmsBrandService pmsBrandService;

    //生成日志Logger对象
    private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);

    @ApiOperation("获取所有品牌类别")
    @GetMapping("/listAll")
    public CommonResult listAll(){
        return CommonResult.success(pmsBrandService.listAllBrand());
    }

    @ApiOperation("添加品牌")
    @PostMapping("/create")
    public CommonResult createBrand(PmsBrand pmsBrand){
        boolean flag = pmsBrandService.createBrand(pmsBrand);
        if (flag){
            return CommonResult.success();
        }else {
            LOGGER.info("createBrand操作失败");
            return CommonResult.failed();
        }
    }
}

实体类注解

@ApiModel
@ApiModelProperty
  • value
  • required
  • example

实例

Swagger2
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
package com.yancy0109.mall.mbg.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;

//Swagger3 实体类需要@ApiModel
@ApiModel
public class PmsBrand implements Serializable {
    private Long id;

    private String name;

    @ApiModelProperty(value = "首字母")
    private String firstLetter;

    private Integer sort;

    @ApiModelProperty(value = "是否为品牌制造商：0->不是；1->是")
    private Integer factoryStatus;

    private Integer showStatus;

    @ApiModelProperty(value = "产品数量")
    private Integer productCount;

    @ApiModelProperty(value = "产品评论数量")
    private Integer productCommentCount;

    @ApiModelProperty(value = "品牌logo")
    private String logo;

    @ApiModelProperty(value = "专区大图")
    private String bigPic;

    @ApiModelProperty(value = "品牌故事")
    private String brandStory;

    private static final long serialVersionUID = 1L;
	
	方法省略.......
}
Swagger3

略有区别

1
@ApiModelProperty(value ="邮费", required =true, example ="0.00")

访问Url

Swagger2

/swagger-ui.html

Swagger3

/swagger-ui/index.html

Swagger3增强

/doc.html