Swagger 配置信息详解(涉及源码分析)

先来说说 Swagger 有什么用,相较于使用 markdown 或者 word 写接口文档,Swagger 自动生成 API 文档,然后在 web 端暴露,并且 API 文档与 API 定义同步更新,这解决了前后端交互时接口更改但协商不及时的问题。另外,Swagger 还内置了在线测试功能,使得开发与接口测试一条龙,因此 Swagger 现在被很多公司使用。

Swagger 需要引入两个依赖包:

<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>

注意:本篇是基于 SpringBoot 来构建

  1. Swagger 是在 web 端显示,所以还需要引入 starter-web
  2. Swagger2 要求 JDK 版本至少是 1.8,否则无法运行

使用 Swagger 总的分为两步:

  1. 写配置类
  2. 使用注解

本篇我们就来看看如何编写配置类,关于有哪些注解请看下一篇

创建配置类,启动 Swagger

Swagger 的实例 Bean 是 Docket,所以通过配置 Docket 实例来配置 Swaggger。

下面,我们新建一个 SwaggerConfig:

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
    
    @Bean // 构建并配置 Docket 对象
    public Docket docket() {
    }
}

至此,我们其实已经能将 Swagger 启动起来了。启动 SpringBoot 项目,浏览器输入 http://localhost:8080/swagger-ui.htm,就可以看到它的界面:

在这里插入图片描述

但里面的东西显然不是我们想要的,我们需要根据实际情况进行配置,比如接口文档名称,作者信息等。那我们该怎么配置 Docket 对象呢?

1.Docket 源码分析

打开 Docket 的源码,我们可以看见 Docket 提供了很多可以配置的属性,并且提供了相应的 setter(注:方法与属性名同名,返回值是 this(链式编程))

在这里插入图片描述

可以看到,它设置默认的分组 DEFAULT_GROUP_NAME 是 default,没错,这就和右上角的 spec 对应上了:

在这里插入图片描述

另外,还有很多我们可以自行配置的属性,下面我们来就来看看其中比较重要的几个…

2.DocumentationType 文档类型

可以看到 Docket 的构造函数需要一个 DocumentationType 作为参数,我们点进它的源码看看:

在这里插入图片描述

可以看到,它提供了三个构造好的 DocumentationType 常量,设置了使用 Swagger 哪个版本。

我们现在一般使用的是 Swagger2,所以在构造 Docket 对象时传入 DocumentationType.SWAGGER_2:

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
    
    @Bean // 构建并配置 Docket 对象
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

3.ApiInfo 基本信息

ApiInfo 见名知意,提供了一些基本信息的配置,这些配置信息可以显示 UI 界面上。同样的,点进它的源码看看

在这里插入图片描述
可以看到,它提供了 8 个可以配置属性,根据名字也能猜出其中的意思。

  • version:API 版本
  • title:文档标题
  • description:文档描述
  • termsOfServiceUrl:团队链接
  • license:许可
  • licenseUrl:许可链接
  • contact:联系人信息
  • vendorExtensions:扩展信息

这里注意,在 ApiInfo 中还有一个默认配置 DEFAULT,它看起来是不是很熟悉?没错,它就是我们在不做任何配置下启动 Swagger 显示的基本信息

在这里插入图片描述

现在我们来配置自己的 ApiInfo

注:ApiInfo 中没有提供 setter,所以我们可以通过 ApiInfo 的构造函数去构建,也可以通过 ApiInfoBuilder 去逐项赋值。

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
    
    @Bean // 构建并配置 Docket 对象
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }
    
    // 构建基本配置信息
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文档标题")
                .description("测试的接口文档")
                .version("v2.0")
                .termsOfServiceUrl("baidu.com")
                .contact(new Contact("A minor", "https://blog.csdn.net/weixin_43935927", "3132266573@qq.com"))
                .build();
    }
}

然后重启 SpringBoot 项目
在这里插入图片描述

4.ApiSelectorBuilder 扫描接口

构建 Docket 时通过 select() 方法配置怎么扫描接口,它会返回一个 ApiSelectorBuilder 对象

在这里插入图片描述

点开 ApiSelectorBuilder 源码:
在这里插入图片描述

可以看到,它需要配置的是 requestHandlerSelector 和 pathSelector。

1)requestHandlerSelector

接口扫描方案。通过 ApiSelectorBuilder#apis() 方法配置(也是链式编程),在 RequestHandlerSelectors 提供了配置方案:

在这里插入图片描述

  • any():扫描所有,项目中的所有接口都会被扫描到
  • none():不扫描接口
  • withClassAnnotation():扫描注解
  • withMethodAnnotation():扫描方法上的注解,比如 withMethodAnnotation(GetMapping.class) 只扫描 @GetMapping 标识的 GET 请求
  • withClassAnnotation():扫描类上的注解,比如 withClassAnnotation(Controller.class) 只扫描有 @Controller 注解的类中的接口
  • basePackage():扫描指定路径,比如 basePackage(“com.test.controller”) 只扫描 controller 包的解耦

PS:常用的是 basePackage(),只去扫描 controller 包。

2)pathSelector

接口过滤方案。

有些时候我们并不是希望所有的 Rest API 都呈现在文档上,这种情况下 Swagger2 提供给我们了两种方式配置,一种是基于 @ApiIgnore 注解(见下一篇)另一种是在 Docket 上增加筛选。两种方式的区别是,Docket 配置的规则,可以对多个接口器过滤作用,而 @ApiIgnore 只能作用于单个接口。

本篇我们先来看第二种,这种方式可以通过筛选 API 的 url 来进行过滤;通过 ApiSelectorBuilder#paths() 方法配置,在 PathSelectors 提供了配置方案:

在这里插入图片描述

  • any():任何路径都满足条件
  • none():任何路径都不满足条件
  • regex():通过正则表达式控制
  • ant():通过 ant 控制

PS:常用的是 any(),不做特殊处理。

在 ApiSelectorBuilder 中提供了默认配置方案 DEFAULT,即不扫描所有标有 @ApiIgnore 注解的类和方法,允许所有的请求路径:

在这里插入图片描述

所以,在一开始,我们才会看到 basic-error-controller 中的这些我们自己没配置过的接口

在这里插入图片描述

好了,现在我们来看一下在 SwaggerConfig 中该怎样配置:

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() // 返回 ApiSelectorBuilder 
                .apis(RequestHandlerSelectors.basePackage("com.test.controller")) // 接口扫描方案
                .paths(PathSelectors.any()) // 接口过滤方案
                .build();
}

在 controller 包新建一个 TestController,然后重启项目后就能看到我们自己的接口了,并且 basic-error-controller 也没了。

在这里插入图片描述

5.groupName 分组

groupName 就是上面说的右上角的分组选项,一般项目中不同的开发人员,可以创建不同的分组,默认的分组是 default。所以,我们可以通过配置多个 Docket 去实现分组

@Bean // 构建并配置 Docket 对象
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select() // 返回 ApiSelectorBuilder
            .apis(RequestHandlerSelectors.basePackage("com.xupt.yzh.testswagger.controller")) // 接口扫描方案
            .paths(PathSelectors.any()) // 接口过滤方案
            .build();

}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("打工人2组");
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("打工人3组");
}

在这里插入图片描述

6.useDefaultResponseMessages 默认状态码

点开接口文档中的接口,可以看见,在 Respon 中 Swagger 默认提供了 200,401,403,404 这几个状态码

在这里插入图片描述

但是,在我们实际开发中,大多数都是自定义状态码的;所以,就可以通过 useDefaultResponseMessages(false) 关闭默认状态码。配置如下:

@Bean // 构建并配置 Docket 对象
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .useDefaultResponseMessages(false)
            .select() // 返回 ApiSelectorBuilder
            .apis(RequestHandlerSelectors.basePackage("com.xupt.yzh.testswagger.controller")) // 接口扫描方案
            .paths(PathSelectors.any()) // 接口过滤方案
            .build();

}

重启项目后,可以看到,原先的 401,403,404 没有了

在这里插入图片描述

7.enabled 是否启动 Swagger

我们在开发、测试时候需要启动 Swagger,但是在实际项目发布上线了就要关闭它,因为一旦一些重要的接口暴露是很危险的,而且一直运行着 Swagger 也会浪费系统资源。

所以可以通过 Docket#enable(false) 来关闭 Swagger,但是如果每次都手动操作显得有些笨拙,我们可以根据当前项目的环境来决定是否开启 Swagger。

1)创建两个新的配置文件,application-dev…properties 和 application-por…properties,分别代表正式环境和开发环境的配置。在这两个配置文件中,分别把启动端口设为 8081 和 8080

在这里插入图片描述

2)修改 SwaggerCofing,让它根据环境开启 Swagger

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
    
    @Bean // 构建并配置 Docket 对象
    // 注:这里注入了 Environment 对象,目的是获取系统环境
    public Docket docket(Environment environment) {

        // 设置要显示 swagger 的环境(dev 或者 test)
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .useDefaultResponseMessages(false)
                .select() // 返回 ApiSelectorBuilder
                .apis(RequestHandlerSelectors.basePackage("com.xupt.yzh.testswagger.controller")) // 接口扫描方案
                .paths(PathSelectors.any()) // 接口路径过滤方案
                .build();

    }

3)修改 application.properties,将当前环境置为 dev

在这里插入图片描述

然后重启项目,就可以发现,8080 端口已经无法访问了,但8081 可以。

在这里插入图片描述

Docket 其余的配置信息我在这里不说了,有用到或者想了解的同学可以自行查阅官网文档。

完整代码

@Configuration
@EnableSwagger2 // 启动 Swagger2
public class SwaggerConfig {
    
    @Bean // 构建并配置 Docket 对象
    // 注:这里注入了 Environment 对象,目的是获取系统环境
    public Docket docket(Environment environment) {

        // 设置要显示 swagger 的环境(dev 或者 test)
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .useDefaultResponseMessages(false)
                .select() // 返回 ApiSelectorBuilder
                .apis(RequestHandlerSelectors.basePackage("com.xupt.yzh.testswagger.controller")) // 接口扫描方案
                .paths(PathSelectors.any()) // 接口路径过滤方案
                .build();

    }

    // 构建基本配置信息
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文档标题")
                .description("测试的接口文档")
                .version("v2.0")
                .termsOfServiceUrl("baidu.com")
                .contact(new Contact("A minor", "https://blog.csdn.net/weixin_43935927", "3132266573@qq.com"))
                .build();
    }

    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("打工人2组");
    }

    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("打工人3组");
    }
}
相关推荐
<p> <b><span style="font-size:14px;"></span><span style="font-size:14px;background-color:#FFE500;">【Java面试宝典】</span></b><br /> <span style="font-size:14px;">1、68讲视频课,500道大厂Java常见面试题+100个Java面试技巧与答题公式+10万字核心知识解析+授课老师1对1面试指导+无限次回放</span><br /> <span style="font-size:14px;">2、这门课程基于胡书敏老师8年Java面试经验,调研近百家互联网公司及面试官的问题打造而成,从筛选简历和面试官角度,给出能帮助候选人能面试成功的面试技巧。</span><br /> <span style="font-size:14px;">3、通过学习这门课程,你能系统掌握Java核心、数据库、Java框架、分布式组件、Java简历准备、面试实战技巧等面试必考知识点。</span><br /> <span style="font-size:14px;">4、知识点+项目经验案例,每一个都能做为面试的作品展现。</span><br /> <span style="font-size:14px;">5、本课程已经在线下的培训课程中经过实际检验,老师每次培训结束后,都能帮助同学们运用面试技巧,成功找到更好的工作。</span><br /> <br /> <span style="font-size:14px;background-color:#FFE500;"><b>【超人气讲师】</b></span><br /> <span style="font-size:14px;">胡书敏 | 10年大厂工作经验,8年Java面试官经验,5年线下Java职业培训经验,5年架构师经验</span><br /> <br /> <span style="font-size:14px;background-color:#FFE500;"><b>【报名须知】</b></span><br /> <span style="font-size:14px;">上课模式是什么?</span><br /> <span style="font-size:14px;">课程采取录播模式,课程永久有效,可无限次观看</span><br /> <span style="font-size:14px;">课件、课程案例代码完全开放给你,你可以根据所学知识,自行修改、优化</span><br /> <br /> <br /> <span style="font-size:14px;background-color:#FFE500;"><strong>如何开始学习?</strong></span><br /> <span style="font-size:14px;">PC端:报名成功后可以直接进入课程学习</span><br /> <span style="font-size:14px;">移动端:<span style="font-family:Helvetica;font-size:14px;background-color:#FFFFFF;">CSDN 学院APP(注意不是CSDN APP哦)</span></span> </p>
©️2020 CSDN 皮肤主题: 撸撸猫 设计师:马嘣嘣 返回首页