Swagger

SpingBoot整合swagger

1.导包

1
2
3
4
5
6
7
8
9
10
<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>

2.新建swagger配置类。

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
/**
 * @Author:liZiYuan Date: 2022/7/3  8:03
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
                .paths(PathSelectors.regex("/.*"))
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("SDN流量监控与防御系统接口文档")
                .contact(new Contact("李子园","","mc1753343931@gmail.com"))
                .description("C4项目接口文档")
                .build();

    }
}

3.给Controller加上注解

首先要在整个类前面加上

1
@Api(value = "/",description = "这是所有get方法")

然后在每个接口前加上

1
@ApiOperation(value = "通过这个方法可以获取到cookies",httpMethod = "GET")

例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@Api(value = "/odl")
@RestController
@RequestMapping("/odl")
public class OdlController {
        /**
     * 获取交换机信息 ++++++交换机+++++++++++
     * @return 交换机信息
     */
    @ApiOperation(value = "获取交换机信息",httpMethod = "GET")
    @GetMapping("/getOvsTable")
    public R<List<HostAndOvs>> getOvsTable(){
        final com.zhang.odl_sflow.entity.odlentity.tableflow.JsonRootBean flowInfo = odlService.getFlowInfo("openflow:1");
        final List<HostAndOvs> hostInformation = RInfo.getHostInformation(odlService.getHostInfo());
        return ResultUtils.success(hostInformation,"获取流表信息成功");
    }
}

4.常用注解

@Api 标识⼀个java类型是⽂档类，⽤controller类的类名上
@ApiModel 表⽰⼀个实体类/模型⽂档，⽤在类名上；
@ApiModelProperty 作⽤在属性上，添加属性描述；
@ApiOperation 作⽤在接⼝类的⽅法上，控制⽅法的相关描述；
@ApiImplicitParam 作⽤在接⼝⽅法上，描述单个参数信息，只能作⽤在⽅法上；
@ApiImplicitParams 作⽤在接⼝⽅法上，@ApiImplicitParam参数组；
@ApiParam 作⽤在接⼝⽅法上，描述单个参数信息，属性基本与@ApiImplicitParam⼀样，但可以作⽤在⽅法、参数、属性上；
下⾯分别对每个注解的常⽤参数作讲解。
@Api：
value：字符串，对controller类的作⽤描述，代替原来的description(已过时)，⼀般⽤此属性；
tags：字符串数组，标签组，同样可以描述controller的作⽤；
@ApiModel
value：字符串，模型的简短别名，使得在⽂档的导航中便于识别；
description：字符串，模型的附加描述；
@ApiOperation
value：字符串，⽅法的功能描述；
tags：字符串数组，标签组，同样可以描述⽅法的作⽤；
response：ClassType，显⽰指出返回的对象类型；在响应⽰例中会显⽰出改对象的字段以及⽰例、描述；
code：响应代码，默认200，⼀般不改；
@ApiModelProperty
value：字符串，字段描述；
required：boolean；指定参数是否必须，默认false；
example：字符串，参数值的⽰例
@ApiImplicitParam
name：字符串，参数名；
value：字符串，参数描述；
defaultValue：字符串，参数默认值；
required：boolean，标识是否必须传值，默认false；
dataType：字符串，参数类型，可以是某个类名，也可以是基本数据类型的引⽤类名，如Integer；
example：字符串，参数值⽰例；
@ApiImplicitParams

value：@ApiImplicitParam类型数组，当⽅法有多个@ApiImplicitParam参数时，需要放到@ApiImplicitParams注解中

5.访问端口：

http://IP:SpirngBoot工程端口/swagger-ui.html

image-20220703093631903

如果有强迫症不要basic-error-cotroller的话改下配置类，如下：

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
/**
 * @Author:liZiYuan Date: 2022/7/3  8:03
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
                .apis(RequestHandlerSelectors.basePackage("com.zhang.odl_sflow.controller"))
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("SDN流量监控与防御系统接口文档")
                .contact(new Contact("李子园","","mc1753343931@gmail.com"))
                .description("C4项目接口文档")
                .build();

    }
}

访问就没有了basic-error-cotroller了

image-20220703093825196

高版本SpringBoot报错：

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
org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.21.jar:5.3.21]
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.21.jar:5.3.21]
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.21.jar:5.3.21]
	at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_333]
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155) ~[spring-context-5.3.21.jar:5.3.21]
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123) ~[spring-context-5.3.21.jar:5.3.21]
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935) ~[spring-context-5.3.21.jar:5.3.21]
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586) ~[spring-context-5.3.21.jar:5.3.21]
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:147) ~[spring-boot-2.7.1.jar:2.7.1]
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:734) [spring-boot-2.7.1.jar:2.7.1]
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:408) [spring-boot-2.7.1.jar:2.7.1]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:308) [spring-boot-2.7.1.jar:2.7.1]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1306) [spring-boot-2.7.1.jar:2.7.1]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1295) [spring-boot-2.7.1.jar:2.7.1]
	at com.zhang.odl_sflow.OdlSFlowApplication.main(OdlSFlowApplication.java:11) [classes/:na]
Caused by: java.lang.NullPointerException: null
	at springfox.documentation.spi.service.contexts.Orderings$8.compare(Orderings.java:112) ~[springfox-spi-2.9.2.jar:null]
	at springfox.documentation.spi.service.contexts.Orderings$8.compare(Orderings.java:109) ~[springfox-spi-2.9.2.jar:null]
	at com.google.common.collect.ComparatorOrdering.compare(ComparatorOrdering.java:37) ~[guava-20.0.jar:na]
	at java.util.TimSort.countRunAndMakeAscending(TimSort.java:355) ~[na:1.8.0_333]
	at java.util.TimSort.sort(TimSort.java:220) ~[na:1.8.0_333]
	at java.util.Arrays.sort(Arrays.java:1438) ~[na:1.8.0_333]
	at com.google.common.collect.Ordering.sortedCopy(Ordering.java:855) ~[guava-20.0.jar:na]
	at springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider.requestHandlers(WebMvcRequestHandlerProvider.java:57) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper$2.apply(DocumentationPluginsBootstrapper.java:138) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper$2.apply(DocumentationPluginsBootstrapper.java:135) ~[springfox-spring-web-2.9.2.jar:null]
	at com.google.common.collect.Iterators$7.transform(Iterators.java:750) ~[guava-20.0.jar:na]
	at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-20.0.jar:na]
	at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-20.0.jar:na]
	at com.google.common.collect.MultitransformedIterator.hasNext(MultitransformedIterator.java:52) ~[guava-20.0.jar:na]
	at com.google.common.collect.MultitransformedIterator.hasNext(MultitransformedIterator.java:50) ~[guava-20.0.jar:na]
	at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:249) ~[guava-20.0.jar:na]
	at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:209) ~[guava-20.0.jar:na]
	at com.google.common.collect.FluentIterable.toList(FluentIterable.java:614) ~[guava-20.0.jar:na]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.defaultContextBuilder(DocumentationPluginsBootstrapper.java:111) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.buildContext(DocumentationPluginsBootstrapper.java:96) ~[springfox-spring-web-2.9.2.jar:null]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.start(DocumentationPluginsBootstrapper.java:167) ~[springfox-spring-web-2.9.2.jar:null]
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:178) ~[spring-context-5.3.21.jar:5.3.21]
	... 14 common frames omitted

解决方案：

这个问题困扰了我很久，也在网上找了好多资料，也有些人说springboot版本升级的导致的问题。
找到的解决办法有两种：

  1. 将springboot降级到2.5.7，但这也只是暂时解决问题的办法，不是长久之计；
  2. 从SpringFox迁移到SpringDoc，这种方式虽然可以处理问题，但对于已经上线的项目来说改动量还是有点大。
    这上面两种解决方案都不是我最想要的，最近对Spring Boot 2.6.0的文档进行研究发现，2.6.0开始使用基于PathPatternParser的路径匹配，而Springfox版本一直没有更新还是使用的AntPathMatcher导致了这个问题，要处理问题也很简单，修改yaml文件，将SpringBoot路劲匹配模式修改为AntPathMatcher就可以了，配置如下：spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

修改application.yml文件配置：

1
2
3
4
spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

SpringBoot整合Kenife4j

1.导包

1
2
3
4
5
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
   <version>3.0.3</version>
</dependency>

2.新建配置类

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
@Configuration
// 必须启用swagger
@EnableSwagger2
@EnableKnife4j
public class Knife4jConfiguration {
    @Bean
    public Docket defaultApi2() {
        return  new Docket(DocumentationType.SWAGGER_2) // 选择swagger2版本
                .useDefaultResponseMessages(false)
                // 接口文档的基本信息
                .apiInfo(apiInfo())
                .select()
                // 这里指定Controller扫描包路径(项目路径也行)
                // 方式一：配置扫描：所有想要在swagger界面统一管理的接口，都必须在此包下
                // .apis(RequestHandlerSelectors.basePackage("com.company.project.web.controller.entrance"))
                // 方式二：只有当方法上有@ApiOperation注解时，才能生成对应的接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路径使用any风格（指定所有路径）
                .paths(PathSelectors.any())
                .build();

    }

    /*
     * 设置文档信息主页的内容说明
     * @param:
     * @return: springfox.documentation.service.ApiInfo 文档信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口项目 后台服务API接口文档")
                .description("服务相关接口(knife4j)")
                // 服务Url（网站地址）
                .termsOfServiceUrl("http://localhost:8080/")
                .contact(new Contact("liziyuan",null,"mc1753343931"))
                .version("1.0")
                .build();
    }

}

3.添加注解

同Swagger

4.访问端口

http://IP:SpirngBoot工程端口/doc.html

image-20220713093946919

5.报错解决方案

同Swagger

java
#swagger
Swagger
http://example.com/2022/09/04/Swagger/
作者
liziyuan
发布于
2022年9月4日
许可协议