SpringBoot基于OpenAPI3的接口文档管理快速集成和使用

简介: 本文主要简单介绍SpringCloud2023中进行接口文档管理,方便前后端开发和文档维护。文档管理工具基于开源的knife4j封装的openapi3。

你好,这里是codetrend专栏“SpringCloud2023实战”。

本文主要简单介绍SpringCloud2023中进行接口文档管理,方便前后端开发和文档维护。文档管理工具基于开源的knife4j封装的openapi3。

前言

OpenAPI 3.0(前身为Swagger)是一种RESTful API文档规范。OpenAPI 3.0规范是一种易于阅读和理解、跨平台和语言、提高协作效率、提供API管理和监控的RESTful API文档规范,提高了API设计和开发的效率、可重用性和互操作性。

有以下几个优点:

  • 易于阅读和理解:OpenAPI 3.0使用简单的YAML或JSON格式,描述了API的所有细节,包括资源路径、HTTP方法、请求参数和响应模型等内容。由于其清晰、结构化的语法,开发人员可以很容易地阅读和理解API文档,快速上手使用API。
  • 自动化工具支持:OpenAPI 3.0规范被广泛支持和使用,有许多自动化工具可以基于OpenAPI规范生成客户端代码、测试用例、API文档和Mock数据等。这些工具能够大大提高开发效率,降低开发成本。
  • 跨平台和语言:OpenAPI 3.0是一种独立于编程语言和平台的规范,可以应用于Java、PHP、Python、Node.js等各种语言和环境中。由于标准化的规范,不同团队或公司之间可以更加容易地进行API的交互和集成,提高了系统的可复用性和互操作性。
  • 提高协作效率:OpenAPI 3.0定义了API的标准接口和参数,避免了开发人员之间因理解不一致而产生的差异。它也为项目经理、测试人员和文档编写者等其他团队提供了清晰的API文档,让他们更快地了解API功能和接口规范,提高协作效率。
  • 提供API管理和监控:OpenAPI 3.0支持API管理和监控的自动化工具集成,例如Swagger UI和Swagger Editor等工具,这些工具可以对API进行实时监控和可视化展示,并提供了许多有用的功能,如在线修改API定义、Mock数据生成和API调试等。

OpenAPI3集成

引入pom.xml

  • 引入OpenAPI主要是引入 springdoc-openapi-starter-webmvc-ui
  • 这里使用 knife4j-openapi3-jakarta-spring-boot-starter 快速集成到springboot 3项目,以及使用它提供的增强服务。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <dependencies>
        <!--其他省略-->
        <!-- 引入openapi3接口文档支持 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        </dependency>
    </dependencies>

</project>

修改配置

  • 新增配置文件 application.yml,配置主要是 springdoc 下面的配置,以及 knife4j 下面的增强实现配置。
spring.application.name: client1
# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: io.rainforest.banana.client1.web
# knife4j的增强配置,不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
  basic:
    enable: true
    # Basic认证用户名
    username: yulin
    # Basic认证密码
    password: 123yl.

修改启动类

  • 启动类不需要特殊修改。文档的开启和关闭基于 knife4j.enable控制的。
package io.rainforest.banana.client1;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.openfeign.EnableFeignClients;

@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients
public class Application {
   
    public static void main(String[] args) {
   
        SpringApplication.run(Application.class, args);
    }
}

接口demo

  • 通过访问 http://localhost:10101/client1/swagger-ui.html ,输入账号密码 yulin/123yl. 就可以访问到最新的接口文档。
package io.rainforest.banana.client1.web.demo;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {
   

   @Operation(summary = "普通body请求")
   @PostMapping("/body")
   public ResponseEntity<String> body(String fileResp){
   
       return ResponseEntity.ok(fileResp);
   }

   @Operation(summary = "普通body请求+Param+Header+Path")
   @Parameters({
   
           @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
           @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
           @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
   })
   @PostMapping("/bodyParamHeaderPath/{id}")
   public ResponseEntity<String> bodyParamHeaderPath(@PathVariable("id") String id, @RequestHeader("token") String token, @RequestParam("name")String name, @RequestBody String fileResp){
   
       return ResponseEntity.ok(fileResp+""+",receiveName:"+name+",token:"+token+",pathID:"+id);
   }
}

具体的openapi3注释和文档可以查看官方文档。和swagger的语法结构类似,但是注解名称和属性都还是差异很大的。

以下是一个简单的Swagger2和OpenAPI3的注解映射关系,可以参考:

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

关于作者

来自一线全栈程序员nine的探索与实践,持续迭代中。

欢迎关注或者点个小红心~

目录
相关文章
|
26天前
|
Java 关系型数据库 MySQL
SpringBoot 通过集成 Flink CDC 来实时追踪 MySql 数据变动
通过详细的步骤和示例代码,您可以在 SpringBoot 项目中成功集成 Flink CDC,并实时追踪 MySQL 数据库的变动。
177 43
|
5天前
|
Cloud Native Java Nacos
springcloud/springboot集成NACOS 做注册和配置中心以及nacos源码分析
通过本文,我们详细介绍了如何在 Spring Cloud 和 Spring Boot 中集成 Nacos 进行服务注册和配置管理,并对 Nacos 的源码进行了初步分析。Nacos 作为一个强大的服务注册和配置管理平台,为微服务架构提供
35 14
|
6天前
|
消息中间件 XML 前端开发
springBoot集成websocket实时消息推送
本文介绍了如何在Spring Boot项目中集成WebSocket实现实时消息推送。首先,通过引入`spring-boot-starter-websocket`依赖,配置`WebSocketConfig`类来启用WebSocket支持。接着,创建`WebSocketTest`服务器类,处理连接、消息收发及错误等事件,并使用`ConcurrentHashMap`管理用户连接。最后,前端通过JavaScript建立WebSocket连接,监听消息并进行相应处理。此方案适用于需要实时通信的应用场景,如聊天室、通知系统等。
|
1月前
|
监控 前端开发 Java
SpringBoot集成Tomcat、DispatcherServlet
通过这些配置,您可以充分利用 Spring Boot 内置的功能,快速构建和优化您的 Web 应用。
58 21
|
2月前
|
监控 Java Nacos
使用Spring Boot集成Nacos
通过上述步骤,Spring Boot应用可以成功集成Nacos,利用Nacos的服务发现和配置管理功能来提升微服务架构的灵活性和可维护性。通过这种集成,开发者可以更高效地管理和部署微服务。
250 17
|
2月前
|
XML JavaScript Java
SpringBoot集成Shiro权限+Jwt认证
本文主要描述如何快速基于SpringBoot 2.5.X版本集成Shiro+JWT框架,让大家快速实现无状态登陆和接口权限认证主体框架,具体业务细节未实现,大家按照实际项目补充。
103 11
|
2月前
|
缓存 安全 Java
Spring Boot 3 集成 Spring Security + JWT
本文详细介绍了如何使用Spring Boot 3和Spring Security集成JWT,实现前后端分离的安全认证概述了从入门到引入数据库,再到使用JWT的完整流程。列举了项目中用到的关键依赖,如MyBatis-Plus、Hutool等。简要提及了系统配置表、部门表、字典表等表结构。使用Hutool-jwt工具类进行JWT校验。配置忽略路径、禁用CSRF、添加JWT校验过滤器等。实现登录接口,返回token等信息。
500 12
|
2月前
|
存储 安全 Java
Spring Boot 3 集成Spring AOP实现系统日志记录
本文介绍了如何在Spring Boot 3中集成Spring AOP实现系统日志记录功能。通过定义`SysLog`注解和配置相应的AOP切面,可以在方法执行前后自动记录日志信息,包括操作的开始时间、结束时间、请求参数、返回结果、异常信息等,并将这些信息保存到数据库中。此外,还使用了`ThreadLocal`变量来存储每个线程独立的日志数据,确保线程安全。文中还展示了项目实战中的部分代码片段,以及基于Spring Boot 3 + Vue 3构建的快速开发框架的简介与内置功能列表。此框架结合了当前主流技术栈,提供了用户管理、权限控制、接口文档自动生成等多项实用特性。
93 8
|
3月前
|
XML Java API
Spring Boot集成MinIO
本文介绍了如何在Spring Boot项目中集成MinIO,一个高性能的分布式对象存储服务。主要步骤包括:引入MinIO依赖、配置MinIO属性、创建MinIO配置类和服务类、使用服务类实现文件上传和下载功能,以及运行应用进行测试。通过这些步骤,可以轻松地在项目中使用MinIO的对象存储功能。
185 5
|
4月前
|
消息中间件 Java Kafka
什么是Apache Kafka?如何将其与Spring Boot集成?
什么是Apache Kafka?如何将其与Spring Boot集成?
119 5