【全网最新-首发】Springfox 3.0.0（包含springfox-swagger2-3.0.0）即OpenAPI 3的发布与系统集成

一. 前言（open api 、swagger、springfox 和springdoc简介）

open api 简介

OpenApi是业界真正的 api 文档标准，一个规范，好比java里面一个抽象的概念。
它即是一个抽象类，只是提供了一个api文档规范的抽象方法，该方法目前被两大非官方实现了，一个是springfox，另一个是springdoc。

swagger 简介

1. swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。
2. 国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。

springfox 简介

1. SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。
2. 截至2020年4月，都未支持 OpenAPI3 标准。
3. 此版本实现较springdoc来讲，实现不是很规范和正式，少了很多架构上的灵活性，维护更新也不如springdoc活跃。但本文却着重介绍springfox与springboot的集成，旨在针对众多国内使用springfox 较多的程序员，但笔者还是建议大家放弃使用springfox，选择springdoc的实现。
4. 若喜欢springdoc实现的朋友，请参阅：Springfox/swagger迁移springdoc-openapi & springdoc-openapi最新版本和springboot应用集成

二. SpringFox 3.0.0 发布

1. SpringFox 3.0.0 发布了，SpringFox 的前身是 swagger-springmvc，是一个开源的 API doc 框架，可以将 Controller 的方法以文档的形式展现。
2. 首先，非常感谢社区让我有动力参与这个项目。在这个版本中，在代码、注释、bug报告方面有一些非常惊人的贡献，看到人们在问题论坛上跳槽来解决问题，我感到很谦卑。它确实激励我克服“困难”，开始认真地工作。有什么更好的办法来摆脱科维德的忧郁！
3. 注意：这是一个突破性的变更版本，我们已经尽可能地保持与springfox早期版本的向后兼容性。在2.9之前被弃用的api已经被积极地删除，并且标记了将在不久的将来消失的新api。所以请注意这些，并报告任何遗漏的内容。

A. 此版本的亮点

1. Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
2. Spring Integration支持（非常感谢反馈）。
3. springboot支持springfox Boot starter依赖性（零配置、自动配置支持）。
4. 具有自动完成功能的文档化配置属性。
5. 更好的规范兼容性与2.0。
6. 支持OpenApi 3.0.3。
7. 零依赖（几乎只需要spring-plugin，pswagger-core](https://github.com/swagger-api/swagger-core)，现有的swagger2注释将继续工作并丰富openapi3.0规范。

B. 兼容性说明

1. 需要Java 8
2. 需要Spring5.x（没有在早期版本中测试
3. 需要SpringBoot 2.2+（未在早期版本中测试）

C. 此版本已修补的漏洞

构造函数的参数0弹簧，文件，弹簧.data.rest.EntityServicesProvider需要一个类型为'javax.servlet.ServletContext“那是找不到的。（#3382）作者@desiderati
从2.9.2（#3087）起，@dilipkrish不再遵守模型财产顺序
基本URL与3.0.0错误。快照正在等待@ogerardin提供的更多信息（#3030）
@dilipkrish操作的示例属性不起作用（#2767）
JsonView没有按照@dilipkrish的预期工作（#3373）
@dilipkrish为web flux类型Mono和flux维护（#3354）提供智能默认值
如何在ApiModel注释的pojo中检测Spring MultipartFile参数，并在Swagger UI（#1370）中显示文件上传按钮@RoseoxHu
无法推断基url。。。springfox-swagger2版本2.9.2（#3001），作者@Lomboska
大摇大摆-用户界面以及jquery1.8.0。最小js无法使用@thomashoef的Sprint Boot 2（#3289）加载AWS Lambda
如果参数为空，则摘要中的ApiInfo将不包含旧值。（#3314）作者@Snap252
@dianfenzhan在响应（#3297）中无法显示带有Map的响应模型的详细信息
502部署到AWS时网关错误，在本地工作。（#3300）作者@alizarouk
Swagger用户界面没有显示@lakshmitharun类型为Byte Array（#3364）的RequestBody的fileupload按钮
POST请求过程中缺少“content type”标题，swagger ui screen（#3353）中缺少@gwcakep的属性
springfox-swagger2:3.0.0-SNAPSHOT生成@josuemojena的bean的requestMappingHandlerAdapter（#3342）冲突
@Tandolf启动spring boot server（#2907）时的无限循环
springfox swagger 3.0.0-SNAPSHOT-JSON模式没有像@pmroch在te update（#3343）之前那样生成
当使用Map<String，Map<String，List>>作为响应类型时，JSON中缺少#ref。（#3356）作者@vpm911
Swagger用户界面无法通过@mobasherswl提交带有文件附件和JSON参数（#3311）的表单数据
NPE开启EnumMapper.MaybeadAllowableValuestoParameter(java:117枚举映射器)（#3339）作者@othellico
在3.0.0-SNAPSHOT中，使用ModelAndView参数，会出现一个错误日志。（#3380）作者@wangxin
@dilipkrish的ResponseHeader没有按预期工作（#3374）
ResponseHeader批注未解析？（#2684）作者@watery
Swagger不尊重@guan25的Jackson@jsonignoreperties注释（#2613）
@ExampleProperty/value被@napolev忽略（#3037）
无法扫描文档上下文默认值java.lang.NullPointerException：null（#3303）作者@WesleyBlancoYuan
Oauth 2.0 redirect_uri params不是使用@Tqup3的3.0.0-SNAPSHOT（#3368）的绝对URL
当您“试用”@dilipkrish的api（#3351）时，Swagger ui错误地使用了基路径
SecurityContext@Aitor1405仅使用operationSelector（#3361）时的操作未检查行为的安全性
springfox-swagger2:3.0.0-SNAPSHOT访问被@kentilini拒绝：springfox-swagger2-3.0.0-20200629.123820-84.jar（#3357）
swagger-2.9.1/csrf is 404（#2603），作者@hxiugangxh
找不到与@mdsina的3.0-SNAPSHOT和Spring WebFlux（#3348）中的键匹配的模型
当请求参数为@SarveshSharma06的集合数组（#3321）时，Swagger不接受@ApiParam的AllowableValues
Docket.apinifo@jensgram从不恢复默认值（#3327）
Spring-fox不接受@manya0810的uuid（#3329）的大小参数
使用时javax.validation.constraints方法参数的注释，参数被@zx472010602识别为请求主体（#3338）
当使用@EnableSwagger2WebFlux时，@DongDDo无法启动bean“documentationPluginsBootstrapper”（#3340）
将实现版本添加到清单.MF（#3341）作者@seregamorph
@fischelt在弹簧靴2.0.1（#2345）中出现异常
在重复的对象名中添加带有数字的后缀，如“_1”。（#3014）作者@pitzcarraldo
springfoxbean Validations@Size注释不能在@shouldnotappearcalm的列表（#3255）上正常工作
@csegedicsaba的SpringDataRest，带多个DTO-s（#3082）
ModelBuilder中的鉴别器字段设置不正确（打字错误？）（#3118）作者@weaselflink
SpringRestDocsOperationBuilderPlugin不会从@ogerardin的jar（#3178）加载资源
@apiparm（example=“..”）不适用于@StasKolodyuk的@RequestBody（#2822）
SpringDataRest Pageable resorce page和size参数由@csegedicsaba用错误的类型（#3075）生成
@diegobmd使用X-Forwarded-Prefix和ForwardedHeaderFilter（#2622）时出错
没有使用Webflux、Swagger 3.0.0-SNAPSHOT和@Numbernick的spring集成（#2967）生成API
@rfigeroa在文档中键入（#2665）
从2.9.0版开始，由于@dbaje需要spring4.3.3代码帮助（#2511），带有@PathVariable的api不再被使用

三. 系统如何集成？

A. springfox-3.0 maven依赖加入

openapi3依赖添加，现在非常方便，不像以往2.9.2版本需要好几个依赖，现在只需添加一个
springfox-boot-starter依赖即可，如下所示：

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-boot-starterartifactId>
    <version>3.0.0version>
dependency>

B. @EnableOpenApi注解添加

swagger2-3.0集成其实质是OpenApi 3的集成，因此需要在类上添加@EnableOpenApi注解，如下所示：

@Configuration
@EnableOpenApi
public class Swagger3Configuration

C. DocumentationType需指向OAS_30

Docket构造函数中的DocumentationType指向，如下所示：

    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")
                
                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(enable)

D. OpenApi 3集成完整示例

OpenApi 3 java配置代码，通用型，如下所示：

/**
 * 
Springfox-swagger 3.0.0配置
 * 
 * @author lilinhai
 * @since 2020-07-13 10:46
 * @version V1.0
 */
@Configuration
@EnableOpenApi
public class Swagger3Configuration implements WebMvcConfigurer
{
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
     */
    @Value("${nature.restApi.enabled}")
    private Boolean enable;
    
    /**
     * 项目应用名
     */
    @Value("${application.name}")
    private String applicationName;
    
    /**
     * 项目版本信息
     */
    @Value("${application.version}")
    private String applicationVersion;
    
    /**
     * 项目描述信息
     */
    @Value("${application.description}")
    private String applicationDescription;
        
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")
                
                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(enable)
                
                // 将api的元信息设置为包含在json ResourceListing响应中。 
                .apiInfo(apiInfo())
                
                // 选择哪些接口作为swagger的doc发布
                .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                .build()
                
                // 支持的通讯协议集合
                .protocols(newHashSet("https", "http"))
                
                // 授权信息设置，必要的header token等认证信息
                .securitySchemes(securitySchemes())
                
                // 授权信息全局应用
                .securityContexts(securityContexts());
    }
    
    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo()
    {
        return new ApiInfoBuilder().title("Sinhy " + applicationName + " Api Doc")
                .description(applicationDescription)
                .contact(new Contact("JetLi", null, "[email protected]"))
                .version("Application Version: " + applicationVersion + ", Spring Boot Version: " + SpringBootVersion.getVersion())
                .build();
    }
    
    /**
     * 设置授权信息
     */
    private List<SecurityScheme> securitySchemes()
    {
        return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "pass"));
    }
    
    /**
     * 授权信息全局应用
     */
    private List<SecurityContext> securityContexts()
    {
        return Collections.singletonList(
                SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[] {new AuthorizationScope("global", "")}))).build());
    }
    
    @SafeVarargs
    private final <T> Set<T> newHashSet(T... ts)
    {
        if (ts.length > 0)
        {
            return new LinkedHashSet<>(Arrays.asList(ts));
        }
        return null;
    }
    
    /**
     * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
     */
    @SuppressWarnings("unchecked")
    public void addInterceptors(InterceptorRegistry registry)
    {
        try
        {
            Field registrationsField = ClassUtils.getField(InterceptorRegistry.class, "registrations");
            List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null)
            {
                for (InterceptorRegistration interceptorRegistration : registrations)
                {
                    interceptorRegistration
                        .excludePathPatterns("/swagger**/**")
                        .excludePathPatterns("/webjars/**")
                        .excludePathPatterns("/v3/**")
                        .excludePathPatterns("/doc.html");
                }
            }
        }
        catch (Exception e)
        {
            
        }
    }
    
}

E. 系统启动效果展示

系统启动成功后，访问地址从以前的/swagger-ui.html变成/swagger-ui/index.html，如下所示：

F. 切换成bootstrap-ui

由于springfox目前是最新的3.0版本，bootstrap-ui目前暂时还没有及时更新，需要等待后续更新后发布到
该博客，敬请期待。

四. 下一篇Springfox迁移springdoc-openapi

注：以上篇幅介绍的内容，此方案虽然也是当前api文档生成的最新款，但是已经不是最佳方案。
springfox目前只是国内的人用的相对多一些，取而代之的便是springdoc-openapi，欢迎阅读下一篇笔者推荐的最佳openapi集成方案

【全网最新-首发】Springfox迁移springdoc-openapi & springdoc-openapi最新版本和springboot应用集成