spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档

本文链接：https://blog.youkuaiyun.com/m0_37809146/article/details/87160740

一、概念综述

1.1 SpringFox

SpringFox 是一个开源的 API 文档框架，它的前身是 Swagger-SpringMVC ，能够完美的支持 SpringMVC 并将其中接口方法自动转换为接口文档。目前 SpringFox 正致力于对更多 JSON API 规范和标准的扩展和支持，例如：swagger，RAML 和 jsonapi。

1.2 Swagger

Swagger 是一个规范框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，支持 API 全生命周期的开发和管理。它是一个综合的开源项目，包含 swagger-core、swagger-ui、swagger-codegen、swagger-editor 等多个子项目：

swagger-core：Swagger Core 是 OpenAPI 规范（以前称为 Swagger 规范）的 Java 实现。
swagger-ui：根据可视化文档，提供与 API 资源的可视化交互。
swagger-codegen：开源的代码生成器，根据 Swagger 定义的 RESTful API 可以自动建立服务端和客户端的连接。
swagger-editor：开源的 API 文档编辑器。

下图为 swagger-ui 提供的文档可视化界面示例：

1.3 关联关系

OpenAPI、Swagger、SpringFox 之间的关联关系可以表述为：Swagger Core 是 Open API 规范的 Java 实现，而 SpringFox 则提供了 Swagger 与 Spring 的集成支持。

二、集成 Swagger 2.0

2.1 基本依赖

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.2 Swagger 配置

进行 Swagger 个性化配置，并使用 @EnableSwagger2 开启 Swagger 支持。另外，虽然 Swagger 是一个非常易用的接口调试插件，但是有可能会导致接口信息泄露，所以建议在开发环境和测试环境开启，但在生产环境关闭。这里一共给出三种 Swagger 开启和关闭的切换方法：

如下面代码所示，在配置文件中增加自定义的开关参数，并在创建 Docket 时，在链式调用的 enable() 方法中传入。
在 SwaggerConfig 配置类上添加 @Profile({"dev","test"}) 注解，指明仅在开发环境和测试环境下激活此配置，并在打包部署时使用 spring.profiles.active 指明具体的环境。
在配置文件中配置自定义的开关参数，并在 SwaggerConfig 配置类上添加 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true")，指明配置类的生效条件。@ConditionalOnProperty 注解能够控制某个配置类是否生效。具体操作是通过 name 和 havingValue 属性来实现，name 对应配置文件中的某个属性，如果该值为空，则返回 false；如果值不为空，则将该值与 havingValue 指定的值进行比较，如果一样则返回 true；否则返回 false。如果返回值为 false，则对应的配置不生效；为 true 则生效。

以下是第一种开关配置方式的使用示例：

/**
 * @description :  Swagger 配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
   
   

    @Value("${swagger.enable}")