Swagger2和Swagger3用法简介及常见踩坑汇总

导入需要的包

地址

Swagger2需要的包

1. Springfox Swagger2
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>3.0.0</version>
</dependency>
2. Springfox Swagger UI
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>3.0.0</version>
</dependency>

Swagger3需要的包

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

优化的swagger文档starter

直接导这个，不需要上面的其他包
访问地址是http://localhost:8080/doc.html

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>3.0.3</version>
</dependency>

过滤无用请求

//注意标黄的地方要求能匹配到你所有的接口路径，比如我的例子中两个接口都是以demo开始的，/demo/mockInvoke和/demo/mockInvoke2
@Bean
Docket mySwagger() {
    return new Docket(DocumentationType.OAS_30).useDefaultResponseMessages(false)
            .produces(Stream.of("application/xml", "application/json")
                    .collect(Collectors.toSet())).select()
            .paths(PathSelectors.regex("/error").negate()).build()
            .protocols(Stream.of("http", "https").collect(Collectors.toSet()));
}

编写Springboot程序，访问Swagger-ui.html

在SpringBoot启动类上添加@EnableSwagger2注解
注意：不管是swagger2还是swagger3，目前的注解都是@EnableSwagger2，还没有更新。
@EnableSwagger2是springfox提供的液体个注解，代表swagger2相关的技术开启。
会扫描当前类所在包，及子包中的所有类型中的注解。做swagger文档的定值。

Swagger2访问地址：http://localhost:8080/swagger-ui.html
Swagger3访问地址：http://localhost:8080/swagger-ui/ (注意斜杠)

在项目中添加一个类，来对API文档主页的展示信息进行配置

package com.dai.learningsystem.config;


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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfiguration {
    /**
     * 创建Docket类型的对象。并使用spring容器管理。
     * Docket是Swagger中的全局配置对象。
     *
     * @return
     */
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        //这里写的是API文档页面上的信息
        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(
                        new Contact(
                                "YiFan Dai",             //是文档的发布者名称
                                "http://alvis.club",       //文档发布者的网站地址。一般是企业网站
                                "ivan.dai@nf-3.com")     //文档发布者的电子邮箱
                )
                .title("LS系统开发文档")
                .description("LS系统是个人用于规划学习内容以及即使监控自己学习进度的管理系统。\n" +
                        "目前用到了SpringBoot+MySql+Swagger3+mybatis等技术。")
                .version("1.1")
                .build();
        //给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);


        docket = docket
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dai.learningsystem.controller"))//用于配置，扫描哪个子包下的注解
                .paths(
                        PathSelectors.regex("/swagger/.*") //使用正则表达式，约束生成API文档的路径地址，即只有/swagger/开始的请求才生成API文档
                )
                .build();
        return docket;
    }
}

最终效果如下：

其他常用注解用法

@Api

修饰整个类，用于controller类上

@ApiOperation

描述一个接口，用户controller方法上

@ApiParam

单个参数描述

@ApiModel

用来对象接收参数,即返回对象

@ApiModelProperty

对象接收参数时，描述对象的字段

@ApiResponse

Http响应其中的描述，在ApiResonse中

@ApiResponses

Http响应所有的描述，用在

@ApiIgnore

忽略这个API

@ApiError

发生错误的返回信息

@ApiImplicitParam

一个请求参数

@ApiImplicitParam

多个请求参数

更多使用说明，可参考 Swagger 使用手册。https://gumutianqi1.gitbooks.io/specification-doc/content/tools-doc/spring-boot-swagger2-guide.html

踩坑

启动报错：

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.13.jar:5.3.13]
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.13.jar:5.3.13]
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.13.jar:5.3.13]
	at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_131]
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155) ~[spring-context-5.3.13.jar:5.3.13]
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123) ~[spring-context-5.3.13.jar:5.3.13]
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935) ~[spring-context-5.3.13.jar:5.3.13]
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586) ~[spring-context-5.3.13.jar:5.3.13]
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145) ~[spring-boot-2.6.0.jar:2.6.0]
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:730) [spring-boot-2.6.0.jar:2.6.0]
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:412) [spring-boot-2.6.0.jar:2.6.0]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:302) [spring-boot-2.6.0.jar:2.6.0]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1301) [spring-boot-2.6.0.jar:2.6.0]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1290) [spring-boot-2.6.0.jar:2.6.0]
	at com.chuci.chucimanagement.ChuCiManagementApplication.main(ChuCiManagementApplication.java:10) [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-25.1-jre.jar:na]
	at java.util.TimSort.countRunAndMakeAscending(TimSort.java:355) ~[na:1.8.0_131]
	at java.util.TimSort.sort(TimSort.java:220) ~[na:1.8.0_131]
	at java.util.Arrays.sort(Arrays.java:1438) ~[na:1.8.0_131]
	at com.google.common.collect.Ordering.sortedCopy(Ordering.java:852) ~[guava-25.1-jre.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$6.transform(Iterators.java:785) ~[guava-25.1-jre.jar:na]
	at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-25.1-jre.jar:na]
	at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-25.1-jre.jar:na]
	at com.google.common.collect.Iterators$ConcatenatedIterator.hasNext(Iterators.java:1332) ~[guava-25.1-jre.jar:na]
	at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:270) ~[guava-25.1-jre.jar:na]
	at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:234) ~[guava-25.1-jre.jar:na]
	at com.google.common.collect.FluentIterable.toList(FluentIterable.java:617) ~[guava-25.1-jre.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.13.jar:5.3.13]
	... 14 common frames omitted

解决方法1

springboot版本过高，缺少swagger运行环境，降低到2.5.7即可。

解决方法2

在application.yml中添加一条配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

或在application.properties中添加spring.mvc.pathmatch.matching-strategy=ant_path_matcher

posted @ 2021-10-15 14:27 iiiiiiiivan 阅读(3875) 评论(0) 编辑收藏举报

刷新页面返回顶部

登录后才能查看或发表评论，立即登录或者逛逛博客园首页

阅读排行：
· 25岁的心里话
· 闲置电脑爆改个人服务器（超详细） #公网映射 #Vmware虚拟网络编辑器
· 基于 Docker 搭建 FRP 内网穿透开源项目（很简单哒）
· 零经验选手，Compose 一天开发一款小游戏！
· 一起来玩mcp_server_sqlite，让AI帮你做增删改查！！

2025年3月

日

一

二

三

四

五

六

iiiiiiiivan

Swagger2和Swagger3用法简介及常见踩坑汇总

导入需要的包

地址

Swagger2需要的包

Swagger3需要的包

优化的swagger文档starter

编写Springboot程序，访问Swagger-ui.html

在项目中添加一个类，来对API文档主页的展示信息进行配置

其他常用注解用法

@Api

@ApiOperation

@ApiParam

@ApiModel

@ApiModelProperty

@ApiResponse

@ApiResponses

@ApiIgnore

@ApiError

@ApiImplicitParam

@ApiImplicitParam

踩坑

解决方法1

解决方法2

搜索

常用链接

我的标签

随笔分类

随笔档案

阅读排行榜

评论排行榜

推荐排行榜

最新评论