SpringBoot整合OpenApi的实践

目录
  • SpringBoot整合OpenApi
    • OpenAPI依赖
    • 编写配置类
    • 改造优化
    • OpenAPI常用注解介绍
      • 实体类
      • controller类
      • 演示

网上经常可以看到OpenAPI和Swagger相关的词汇,总是傻傻分不清,这里先简单介绍一下Swagger个OpenAPI的联系。

OpenAPI是规范;Swagger是实现规范的工具。

OpenAPI 3.0是该规范的第一个正式版本,因为它是由SmartBear Software捐赠给OpenAPI Initiative,并在2015年从Swagger规范重命名为OpenAPI规范。

OpenAPI是规范的正式名称。该规范的开发是由OpenAPI Initiative推动的,该倡议涉及更多来自技术领域不同领域的30个组织-包括Microsoft,Google,IBM和CapitalOne。

领导Swagger工具开发的公司Smartbear Software也是OpenAPI Initiative的成员,帮助领导了规范的发展。

SpringBoot整合OpenApi

确保SpringBoot版本在2.x级以上。

OpenAPI依赖

引入OpenApi依赖

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

编写配置类

编写配置类,并手动装配@EnableOpenApi

@EnableOpenApi
@Configuration
public class OpenApiConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(apis())
                .paths(PathSelectors.any())
                .build()
                .enable(true);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("项目名称")
                .description("项目描述")
                .termsOfServiceUrl("项目地址")
                .version("API版本")
                .license("公司的license")
                .licenseUrl("公司的license地址")
                .build();
    }

    private Predicate<RequestHandler> apis() {
        return RequestHandlerSelectors.basePackage("controller包的路径");
    }
}

到这里SpringBoot就整合OpenAPI成功了。需要一提的是,OpenAPI不仅可以通过扫描controller包的路径生成OpenAPI,也可以通过扫描@ApiOperation来生成OpenAPI。

改造优化

上面的示例通过硬编码的形式,所以无法进行代码的复用,而且每次更新配置的时候,都需要更改代码,比如我们的项目在开发或者测试环境时,我们希望能正常使用OpenAPI但是在生产环境需要禁用OpenAPI。
在工程学的角度,常用的做法是尽量通过更改配置的形式,问不是更改代码。基于此,我们可以借助SpringBoot的配置功能,对上述代码进行改造。

新增OpenApi配置类

@Data
@Component
@ConfigurationProperties(prefix = "example.web.swagger")
public class SwaggerProperties {
    /**
     * 是否swagger3启用,默认不启用
     */
    private Boolean enable = false;
    /**
     * 扫描包路径,可以不指定,系统会通过自动扫描{@link io.swagger.annotations.ApiOperation}
     */
    private String basePackage;
    /**
     * 标题
     */
    private String title;
    /**
     * 应用描述
     */
    private String description;
    /**
     * 服务地址
     */
    private String serviceUrl;
    /**
     * 版本,默认V1.0.0
     */
    private String version = "V1.0.0";
    /**
     * license
     */
    private String license;
    /**
     * licenseUrl
     */
    private String licenseUrl;
}

配置替换硬编码

@Slf4j
@Configuration
@EnableOpenApi
public class OpenApiConfiguration {

    @Resource
    private SwaggerProperties swaggerProperties;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(apis())
                .paths(PathSelectors.any())
                .build()
                .enable(isEnable());
    }

    private Boolean isEnable() {
        Boolean enable = swaggerProperties.getEnable();
        if (enable) {
            log.info("\nEnable Swagger3...");
        }
        return enable;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .termsOfServiceUrl(swaggerProperties.getServiceUrl())
                .version(swaggerProperties.getVersion())
                .license(swaggerProperties.getLicense())
                .licenseUrl(swaggerProperties.getLicenseUrl())
                .build();
    }

    private Predicate<RequestHandler> apis() {
        String basePackage = swaggerProperties.getBasePackage();
        // 默认通过扫描`ApiOperation`如果配置了包扫描路径,使用配置的包扫描路径
        return Strings.isNullOrEmpty(basePackage) ? withMethodAnnotation(ApiOperation.class) : basePackage(basePackage);
    }
}

通过这样的简单改造后,我们就可以完全通过配置文件的形式配置OpenApi

示例配置

example:
  web:
    swagger:
      enable: true
      title: 演示OpenAPI
      description: 演示OpenAPI
      base-package: com.example.controller

OpenAPI常用注解介绍

这里通过使用代码演示注解的使用

实体类

需要在用户的VO实体类标注@ApiModel并说明该类的作用, 属性上通过@ApiModelProperty解析属性的作用,并通过required值约定该属性是否可以为空 可以通过example说明该属性的用例值

@Data
@ApiModel("用户信息")
public class UserVO {

    @ApiModelProperty(value = "用户id", required = true, example = "asdf124")
    private String userId;

    @ApiModelProperty(value = "用户名称", required = true)
    private String username;

    @ApiModelProperty(value = "用户年龄")
    private Integer age;
}

controller类

这里主要通过用户注册和用户信息接口演示。

在配上通过@Api标注该类的功能;通过@ApiOperation说明接口的功能,如果传入的数据不是实体类,而是一个基本数据类型,可以通过@ApiParam解释参数的作用

@RequestMapping("user")
@RestController
@Api(tags = "用户中心")
public class UserController {

    @ApiOperation("用户注册")
    @PostMapping
    public R<Void> register(@RequestBody UserVO userVO) {
        // todo
        return R.ok();
    }

    @ApiOperation("通过Id获取用户信息")
    @GetMapping
    public R<UserVO> userInfo(@ApiParam(value = "用户id",required = true) @RequestParam String userId) {
        // todo
        return R.ok(new UserVO());
    }
}

演示

启动项目,通过访问IP:PORT/swagger-ui/index.html即可看到swagger界面

到此这篇关于SpringBoot整合OpenApi的实践的文章就介绍到这了,更多相关SpringBoot整合OpenApi内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • spring boot整合CAS Client实现单点登陆验证的示例

    本文介绍了spring boot整合CAS Client实现单点登陆验证的示例,分享给大家,也给自己留个笔记,具体如下: 单点登录( Single Sign-On , 简称 SSO )是目前比较流行的服务于企业业务整合的解决方案之一, SSO 使得在多个应用系统中,用户只需要 登录一次 就可以访问所有相互信任的应用系统. CAS Client 负责处理对客户端受保护资源的访问请求,需要对请求方进行身份认证时,重定向到 CAS Server 进行认证.(原则上,客户端应用不再接受任何的用户名密码等

  • springboot与mybatis整合实例详解(完美融合)

    简介 从 Spring Boot 项目名称中的 Boot 可以看出来,Spring Boot 的作用在于创建和启动新的基于 Spring 框架的项目.它的目的是帮助开发人员很容易的创建出独立运行和产品级别的基于 Spring 框架的应用.Spring Boot 会选择最适合的 Spring 子项目和第三方开源库进行整合.大部分 Spring Boot 应用只需要非常少的配置就可以快速运行起来. Spring Boot 包含的特性如下: 创建可以独立运行的 Spring 应用. 直接嵌入 Tomc

  • springboot+springmvc+mybatis项目整合

    介绍: 上篇给大家介绍了ssm多模块项目的搭建,在搭建过程中spring整合springmvc和mybatis时会有很多的东西需要我们进行配置,这样不仅浪费了时间,也比较容易出错,由于这样问题的产生,Pivotal团队提供了一款全新的框架,该框架使用了特定的方式来进行配置,从而使开发人员不再需要定义样板化的配置.通过这种方式,Spring Boot致力于在蓬勃发展的快速应用开发领域(rapid application development)成为领导者. 特点: 1. 创建独立的Spring应用

  • spring boot整合spring-kafka实现发送接收消息实例代码

    前言 由于我们的新项目使用的是spring-boot,而又要同步新项目中建的数据到老的系统当中.原来已经有一部分的同步代码,使用的是kafka. 其实只是做数据的同步,我觉得选MQ没必要使用kafka.首先数据量不大,其实搞kafka又要搞集群,ZK.只是用做一些简单数据同步的话,有点大材小用. 没办法,咱只是个打工的,领导让搞就搞吧.刚开始的时候发现有一个spring-integration-kafka,描述中说是基于spring-kafka做了一次重写.但是我看了官方文档.实在是搞的有点头大

  • 详解Spring Boot整合Mybatis实现 Druid多数据源配置

    一.多数据源的应用场景 目前,业界流行的数据操作框架是 Mybatis,那 Druid 是什么呢? Druid 是 Java 的数据库连接池组件.Druid 能够提供强大的监控和扩展功能.比如可以监控 SQL ,在监控业务可以查询慢查询 SQL 列表等.Druid 核心主要包括三部分: 1. DruidDriver 代理 Driver,能够提供基于 Filter-Chain 模式的插件体系. 2. DruidDataSource 高效可管理的数据库连接池 3. SQLParser 当业务数据量达

  • springboot整合redis进行数据操作(推荐)

    redis是一种常见的nosql,日常开发中,我们使用它的频率比较高,因为它的多种数据接口,很多场景中我们都可以用到,并且redis对分布式这块做的非常好. springboot整合redis比较简单,并且使用redistemplate可以让我们更加方便的对数据进行操作. 1.添加依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starte

  • 浅谈Springboot整合RocketMQ使用心得

    一.阿里云官网---帮助文档 https://help.aliyun.com/document_detail/29536.html?spm=5176.doc29535.6.555.WWTIUh 按照官网步骤,创建Topic.申请发布(生产者).申请订阅(消费者) 二.代码 1.配置: public class MqConfig { /** * 启动测试之前请替换如下 XXX 为您的配置 */ public static final String PUBLIC_TOPIC = "test"

  • Spring boot Mybatis 整合(完整版)

    本项目使用的环境: 开发工具: Intellij IDEA 2017.1.3 springboot: 1.5.6 jdk:1.8.0_161 maven:3.3.9 额外功能 PageHelper 分页插件 mybatis generator 自动生成代码插件 步骤: 1.创建一个springboot项目: 2.创建项目的文件结构以及jdk的版本 3.选择项目所需要的依赖 然后点击finish 5.看一下文件的结构: 6.查看一下pom.xml: <?xml version="1.0&qu

  • SpringBoot定时任务两种(Spring Schedule 与 Quartz 整合 )实现方法

    前言 最近在项目中使用到定时任务,之前一直都是使用Quartz 来实现,最近看Spring 基础发现其实Spring 提供 Spring Schedule 可以帮助我们实现简单的定时任务功能. 下面说一下两种方式在Spring Boot 项目中的使用. Spring Schedule 实现定时任务 Spring Schedule 实现定时任务有两种方式 1. 使用XML配置定时任务, 2. 使用 @Scheduled 注解. 因为是Spring Boot 项目 可能尽量避免使用XML配置的形式,

  • SpringBoot整合OpenApi的实践

    目录 SpringBoot整合OpenApi OpenAPI依赖 编写配置类 改造优化 OpenAPI常用注解介绍 实体类 controller类 演示 网上经常可以看到OpenAPI和Swagger相关的词汇,总是傻傻分不清,这里先简单介绍一下Swagger个OpenAPI的联系. OpenAPI是规范:Swagger是实现规范的工具. OpenAPI 3.0是该规范的第一个正式版本,因为它是由SmartBear Software捐赠给OpenAPI Initiative,并在2015年从Sw

  • springboot整合EHCache的实践方案

    EhCache 是一个纯Java的进程内缓存框架,具有快速.精干等特点,是Hibernate中默认的CacheProvider. ehcache提供了多种缓存策略,主要分为内存和磁盘两级,所以无需担心容量问题. spring-boot是一个快速的集成框架,其设计目的是用来简化新Spring应用的初始搭建以及开发过程.该框架使用了特定的方式来进行配置,从而使开发人员不再需要定义样板化的配置. 用户登录之后,几乎之后展示任何页面都需要显示一下用户信息.可以在用户登录成功之后将用户信息进行缓存,之后直

  • springboot整合ehcache 实现支付超时限制的方法

    下面给大家介绍springboot整合ehcache 实现支付超时限制的方法,具体内容如下所示: <dependency> <groupId>net.sf.ehcache</groupId> <artifactId>ehcache-core</artifactId> <version>2.6.11</version> </dependency> pom文件中引入ehcache依赖 在类路径下存放ehcache.

  • springboot整合security和vue的实践

    目录 环境 1.security参考资料 认证流程原理: 2.springboot整合security要点 2.1获取登录用户信息 2.2自定义登入登出url 2.3自定义Handler返回json 2.4记住我功能 2.5验证码功能 2.6限制登录次数 2.7密码加密 2.8后台提供接口,返回前端json,整合vue做前端登入登出 3.测试 环境 springboot1.5.9 完整代码,内有sql,先建库,在运行sql建表,sql中已插入测试的数据. https://github.com/2

  • SpringBoot整合sharding-jdbc实现自定义分库分表的实践

    目录 一.前言 二.简介 1.分片键 2.分片算法 三.程序实现 一.前言 SpringBoot整合sharding-jdbc实现分库分表与读写分离 本文将通过自定义算法来实现定制化的分库分表来扩展相应业务 二.简介 1.分片键 用于数据库/表拆分的关键字段 ex: 用户表根据user_id取模拆分到不同的数据库中 2.分片算法 可参考:https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere

  • springboot整合shardingsphere和seata实现分布式事务的实践

    各个框架版本信息 springboot: 2.1.3 springcloud: Greenwich.RELEASE seata: 1.0.0 shardingsphere:4.0.1 maven 依赖        <dependency>         <!--<groupId>io.shardingsphere</groupId>-->         <groupId>org.apache.shardingsphere</group

  • SpringBoot整合SpringSecurity实现JWT认证的项目实践

    目录 前言 1.创建SpringBoot工程 2.导入SpringSecurity与JWT的相关依赖 3.定义SpringSecurity需要的基础处理类 4. 构建JWT token工具类 5.实现token验证的过滤器 6. SpringSecurity的关键配置 7. 编写Controller进行测试 前言 微服务架构,前后端分离目前已成为互联网项目开发的业界标准,其核心思想就是前端(APP.小程序.H5页面等)通过调用后端的API接口,提交及返回JSON数据进行交互.在前后端分离项目中,

  • SpringBoot整合chatGPT的项目实践

    目录 1 添加依赖 2 创建相关文件 2.1 实体类:OpenAi.java 2.2 配置类:OpenAiProperties.java 2.3 核心业务逻辑OpenAiUtils.java 2.4 自动配置类OpenAiAutoConfiguration.java 2.5 在resources文件夹下的META-INF/spring.factories文件中增加配置 2.6 在yml文件上配置token 3 编写测试类 4 补充 4.1 添加依赖 4.2 添加代码 5 总结 1 添加依赖 <!

  • Springboot整合log4j2日志全解总结

    在项目推进中,如果说第一件事是搭Spring框架的话,那么第二件事情就是在Sring基础上搭建日志框架,我想很多人都知道日志对于一个项目的重要性,尤其是线上Web项目,因为日志可能是我们了解应用如何执行的唯一方式. 在18年大环境下,更多的企业使用Springboot和Springcloud来搭建他们的企业微服务项目 ,此篇文章是博主在实践中用Springboot整合log4j2日志的总结. 常用日志框架 java.util.logging:是JDK在1.4版本中引入的Java原生日志框架 Lo

  • SpringBoot整合Swagger和Actuator的使用教程详解

    前言 本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程. SpringBoot整合Swagger 说明:如果想直接获取工程那么可以直接跳到底部,通过链接下载工程代码. Swagger 介绍 Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计.构建.记录以及使用 Rest API.Swagger 主要包含了以下三个部分: Swagger Editor:基于浏览器的编辑器,我们

随机推荐