「尝鲜」SpringBoot 快速整合Swagger 3.0

偷懒的程序员 2020-10-15 13:27:10 ⋅ 476 阅读

第一步:Maven引入Swagger3.0 starter依赖

Maven项目中引入springfox-boot-starter依赖:

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

备注:依赖更加简单,不再需要springfox-swagger2 和 springfox-swagger-ui 这两个依赖。

第二步:增加application.yml配置

swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: 1.0
  application-description: springfox swagger 3.0整合Demo
  try-host: http://localhost:${server.port}
spring:
  application:
    name: springfox-swagger

第三步:启用swagger配置

使用@EnableOpenApi注解,启用swagger配置

@EnableOpenApi
@Configuration
public class SwaggerConfiguration {
}

第四步:启动测试

访问地址:http://127.0.0.1:8080/swagger-ui/index.html image.png

备注:老版本的访问方式为http://127.0.0.1:8080/swagger-ui.html 已经不可用了。

扩展:完整的springfox swagger配置示例

import io.swagger.models.auth.In;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.lang.reflect.Field;
import java.util.*;

@EnableOpenApi
@Configuration
public class SwaggerConfiguration implements WebMvcConfigurer {
    private final SwaggerProperties swaggerProperties;

    public SwaggerConfiguration(SwaggerProperties swaggerProperties) {
        this.swaggerProperties = swaggerProperties;
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")

                // 定义是否开启swagger,false为关闭,可以通过变量控制
                .enable(swaggerProperties.getEnable())

                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())

                // 接口调试地址
                .host(swaggerProperties.getTryHost())

                // 选择哪些接口作为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(swaggerProperties.getApplicationName() + " Api Doc")
                .description(swaggerProperties.getApplicationDescription())
                .contact(new Contact("lighter", null, "123456@gmail.com"))
                .version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
                .build();
    }

    /**
     * 设置授权信息
     */
    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 授权信息全局应用
     */
    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")
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            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.printStackTrace();
        }
    }

}

常用注解说明

@Api:用在controller类,描述API接口

@ApiOperation:描述接口方法

@ApiModel:描述对象

@ApiModelProperty:描述对象属性

@ApiImplicitParams:描述接口参数

@ApiResponses:描述接口响应

@ApiIgnore:忽略接口方法


全部评论: 0

    我有话说:

    软件更新」IntelliJ IDEA 2019.3 发布早期访问版,新特性抢

    地址:https://www.jetbrains.com/idea/nextversion/ (生产环境建议慎用)

    YuebonCore 1.0.1 发布,权限管理及快速开发框架

    YuebonCore是基于.Net5.0开发的权限管理及快速开发框架,整合应用最新技术包括Asp.NetCore MVC、Dapper、AutoFac、WebAPI、Swagger、EF、Vue等

    SpringBoot2.0填坑(一):使用CROS解决跨域并解决swagger 访问不了问题

    公司后台是采用SpringBoot2.0 搭建的微服务架构,前端框架用的是vue 使用前后端分离的开发方式,在开发联调的时候需要进行跨域访问,那么使用CROS解决了跨域问题,但是swagger 却用

    【开源资讯】Spring Boot 2.4.0.M4 发布

    Spring Boot 2.4.0 的第四个里程碑版本发布了,可以从里程碑仓库获取。此版本包含 145 项更新内容,亮点如下:1、改进故障分析器(Failure Analyzer

    微服务架构实战篇:快速入手SpringBoot 2.0,欢迎入坑哦~~~

    SpringBoot 2.0 基本要求Java最低要求8以上,不再支持Java 6 和 7等低版本。

    swagger-admin v1.3.5 已经发布,Swagger 文档管理后台

    swagger-admin v1.3.5 已经发布,这是一个Swagger文档管理后台,可统一管理多个项目的Swagger文档,只需要一个Java8环境,下载后即可运行使用。 支持导入json,非

    Guns 7.0 发布,更简洁的后台管理系统

    新版Guns基于SpringBoot全面升级,完美整合springmvc + shiro + mybatis-plus + beetl! 在不用写xml配置(V1.0)的基础上进一步简化项目配置,让

    Vant 3.0 正式发布:全面拥抱 Vue 3

    历经八个月时长的开发,Vant 3.0 现已正式发布。官方表示,在本次迭代中,其主要工作是基于 Vue 3 重构整个代码仓库和周边生态,并发布 Vant 3.0、Vant Cli 3.0

    【超全教程】SpringBoot 2.3.x 分层构建 Docker 镜像实践

    作者:超级小豆丁 http://www.mydlq.club/article/98/ 目录 什么是镜像分层 SpringBoot 2.3.x 新增对分层的支持 创建测试的 SpringBoot

    Swagger接口文档工具:Knife4j 2.0.7 发布,细节优化

    Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能的工具 文档:https://doc.xiaominfo.com 效果(旧版):http

    FileZilla Client 3.52.0 发布,FTP 客户端

    FileZilla Client 3.49.0-rc1 发布了。FileZilla 是一种快速、可信赖的 FTP 客户端以及服务器端开源程序,具有多种特色、直观的接口。FileZilla

    Spring Initializr 0.1.0 发布,Spring 项目的快速开始生成器

    Spring Initializr 0.1.0 已经发布。 Spring initializr 是一个 Spring 项目的快速开始生成器。其提供了一个可扩展的 API 来生成基于 JVM

    FileZilla Client 3.53.0-rc1 发布,FTP 客户端

    FileZilla Client 3.53.0-rc1 发布了。FileZilla 是一种快速、可信赖的 FTP 客户端以及服务器端开源程序,具有多种特色、直观的接口。FileZilla

    WebMIS 1.0.0 beta.3 发布,全栈开发基础框架

    全栈开发基础框架,包括 PHP / Python / SpringBoot / Phalcon / Flutter / NodeJS / Vue / Swoole / Redis / API 等技术

    SQLite 3.34.0 发布,世界上使用量最大的数据库引擎

    SQLite 3.34.0 发布了,SQLite 是一个 C 实现的 SQL 数据库引擎,它的特点是小型、快速、自包含、高可靠性和功能齐全。SQLite 嵌入在所有手机和大多数计算机中,也捆绑在

    精品推荐:基于SpringBoot2.0的企业级开发脚手架

    SmallBun是参考多个优秀的开源项目及自身学习、经验运用,高度整合封装而成的高效,高性能,强安全性的开源项目,内附Git源码地址

    Scala 3 来了,Dotty 发布 3.0.0-M1 版本

    Dotty 发布了 3.0 的首个里程碑版本 3.0.0-M1,Dotty 作为 Scala 尝试新的语言概念以及编译器技术的研究平台,它最终将成为 Scala 3.0。 Dotty 对

    TestableMock v0.6.0 发布,新增测试参数快速构造工具

    项目介绍 TestableMock是一款由阿里效能团队开源的Java单元测试增强工具,提供四项具有针对性的辅助能力: 快速Mock任意调用:解决传统Mock工具使用繁琐的问题 访问被测类私有成员

    ElasticJob 3.0.0-beta 发布,丰富的报警机制集成

    本周Apache ShardingSphere团队很高兴的向大家宣布: ElasticJob-3.0.0-beta 和 ElasticJob UI-3.0.0-beta 的新版本正式发布了