SpringBoot3整合SpringDoc实现在线接口文档-6ren

SpringBoot3整合SpringDoc实现在线接口文档

转载作者：撒哈拉更新时间：2024-06-17 23:05:26

写在前面

在现目前项目开发中，一般都是前后端分离项目。前端小姐姐负责开发前端，苦逼的我们负责后端开发。

事实是一个人全干，在这过程中编写接口文档就显得尤为重要了。然而作为一个程序员，最怕的莫过于自己写文档和别人不写文档。

大家都不想写文档，那这活就交给今天的主角Swagger来实现了。

一、专业名词介绍

①OpenApi是什么?

解答：OpenApi是一个用于描述、定义和共享 RESTful API 文档的规范。最新规范是 OpenAPI 3.0 。

② Swagger是什么?

解答： Swagger 是一个用于设计和测试 RESTful APIs 的工具.

它提供了API 描述、请求和响应示例、API 测试和文档生成等丰富的功能。最新版本是Swagger3,支持OpenAPI3.0规范。

③ SpringFox 是什么?

SpringFox 是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 2 集成到 Spring 中.

目前国内项目使用的都是它。

github地址：https://github.com/springfox/springfox 。

④springDoc是什么?

解答： Spring-doc也是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 3 集成到 Spring 中。

SpringDoc 支持 Swagger 页面 Oauth2 登录，相较于 SpringFox 而言，它的支撑时间更长，无疑是更好的选择.

但是在国内发展较慢，网上一找资料，出来的基本上是 Swagger2的内容.

地址：https://springdoc.org/ 。

⑤ OpenAPI 、Spring-doc和 Swagger 之间的关系。

解答：OpenAPI 定义了一种标准的格式来表示 API 文档，而 Swagger 是一个实现 OpenAPI 规范的工具。

二、Swagger详细简介

Swagger 江湖人称“丝袜哥”，是一个帮助程序员生成接口文档的利器.

只需要简单配置，就可以生成带有漂亮UI界面的接口文档，而且编写的接口代码变了。

接口文档随之也跟着变，做到了真正的解放双手.

官网https://swagger.io/ 。

Swagger 优点。

号称世界上最流行的API框架
Restful Api 文档在线自动生成器
直接运行，支持在线测试API
不仅仅支持Java，还支持多种语言（如：PHP、Python、Node.js等）

三、小试牛刀

说了这么多Swagger 的优点，接下来就小试牛刀，看看怎么将Swagger集成到SpringBoot中.

3.1、环境介绍

JDK：17
SpringBoot：3.3.0
Springdoc

注：细心的小伙伴可能已经发现了，在springboot3.0之前我用的都是Springfox来集成Swagger管理我们的API接口文档.

但是Springfox已经停止更新了，我们使用的是SpringBoot3 +jdk17 的环境后，Spring官网推荐了Springdoc 来整合swagger 。

3.2 新建一个springboot-web项目

3.3 添加依赖

由于篇幅原因，其他web项目相关依赖这里就不一一贴出来了.

第一个依赖是必须的，而且版本必须大于2.0.0 。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.2.0</version>
</dependency>

注:

我们这里使用的是jdk17+springboot3.3.0 环境，原来swagger的V2和V3都不能用了，小伙伴们一定更要注意这儿。

不能引入的依赖

如果引入上面错误的依赖，项目启动会报下面错误，这时候我们引入上面正确的依赖重新启动项目即可。

报错信息

3.4 编写`HelloController`

新建一个controller包--->建立一个HelloController类。

新建Hellocontroller

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

我们在浏览器中输入“http://localhost:8080/hello” 后回车，出现如下界面，说明我们的hello开发成功了。

hello接口正常访问

3.5 访问swagger接口页面

注：我们这里采用的是openapi ,所以就不用像swagger的V2和v3那样添加配置类了。

浏览器直接输入：http://localhost:8080/swagger-ui/index.html 回车即可看到下面界面。

接口信息

整合swagger是不是很简单呢。

四、修改接口

多种请求方式

从上面截图中我们看到，我们在HelloController 中只定义了一个接口，但是前端UI界面中出来个7种请求方式（GET、PUT、POST、DELETE、OPTIONS、HEAD、PATCH）的接口，这是为什么呢?

解答：@RequestMapping("/hello") 我们接口中只是指定了访问地址，并没有指定请求方式。

我们将注解修改成@RequestMapping(path = "/hello",method = RequestMethod.GET) 。

或者@GetMapping("/hello") 然后重启服务，我们看到界面上就只有一种请求方式的接口了。

get请求方式

五、接口文档常用配置

5.1 配置访问路径

在application.yml中可以自定义api-docs和swagger-ui的访问路径。当然了，如果没配置，默认就是下面路径。

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

5.2 配置接口文档基本信息

① 配置接口基本信息。

新建一个config包--->并在包下建立一个SpringDocConfig配置类。

新建配置类

② 配置接口文档基础信息。

我们在配置类中添加如下代码，。

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置接口文档基本信息
                .info(this.getApiInfo())
                ;
    }

    private Info getApiInfo() {
        return new Info()
                 // 配置文档标题
                .title("SpringBoot3集成Swagger3")
                // 配置文档描述
                .description("SpringBoot3集成Swagger3示例文档")
                // 配置作者信息
                .contact(new Contact().name("程序员小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
                // 配置License许可证信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                // 概述信息
                .summary("SpringBoot3集成Swagger3示例文档aaa")
                .termsOfService("https://www.xiezhrspace.cn")
                // 配置版本号
                .version("2.0");
    }

}

前端页面访问接口文档页面后显示如下。

接口基本信息

② 配置接口servers信息。

接口可能存在多环境，如开发环境、测试环境、生产环境等。

我们可以通过@OpenAPIDefinition 配合servers 属性来配置不同环境，具体配置示例如下。

@OpenAPIDefinition(
        servers = {
                @Server(description = "开发环境服务器", url = "http://localhost:8080"),
                @Server(description = "测试环境服务器", url = "https://test.xiezhr.com")
        }
)
@Configuration
public class SpringDocConfig {
    //...
}

配置完成后，浏览器访问显示如下。

配置servers信息

③ 配置外部文档信息。

有时候我们需要在在线接口文档中可以显示跳转到API的一些外部文档（比如项目部署文档等）。

这个时候我们可以通过@OpenAPIDefinition 配合 externalDocs 属性来配置外部文档。

具体配置如下。

@OpenAPIDefinition(

    externalDocs = @ExternalDocumentation(
        description = "项目编译部署说明",
        url = "http://localhost:8080/deplay/readme.md"
    )
)
@Configuration
public class SpringDocConfig {
    //......
}

配置完后重启服务，浏览器访问接口文档，显示如下。

外部API文档

SpringDocConfig 类完整配置代码如下。

@OpenAPIDefinition(

        servers = {
                @Server(description = "开发环境服务器", url = "http://localhost:8080"),
                @Server(description = "测试环境服务器", url = "https://test.xiezhr.com")
        },
        externalDocs = @ExternalDocumentation(
                description = "项目编译部署说明",
                url = "http://localhost:8080/deplay/readme.md"
        )
)

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置接口文档基本信息
                .info(this.getApiInfo())
                ;
    }

    private Info getApiInfo() {
        return new Info()
                 // 配置文档标题
                .title("SpringBoot3集成Swagger3")
                // 配置文档描述
                .description("SpringBoot3集成Swagger3示例文档")
                // 配置作者信息
                .contact(new Contact().name("程序员小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
                // 配置License许可证信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                //
                .summary("SpringBoot3集成Swagger3示例文档aaa")
                .termsOfService("https://www.xiezhrspace.cn")

                // 配置版本号
                .version("2.0");
    }

  

}

配置完上面信息后，重启服务，浏览器访问：http://localhost:8080/v3/swagger-ui/index.html 。

接口文档基本信息

5.3 配置扫描接口

应用场景:

有时候我们为了业务需要，我们建立了多个包下的接口，如admin包下的，common包下的接口，。

为了安全起见，我们只允许接口文档中访问comm包下面的接口.

在不加任何配置的情况下，所以接口都会默认显示，具体如下。

显示所有接口

配置扫描接口包:

在application.yml中可以自定义要扫描的接口包。

springdoc:
  packages-to-scan: com.xiezhr.swaggerdemo.common.controller

配置好之后重启服务，我们发现前台UI只显示了common包下面的接口了。

只显示common包下面的接口

5.4 配置接口文档开关

使用场景:

为了接口安全，我们一般需要在测试（test）环境或者开发(dev)环境中开启接口文档，而在生产（prod）环境中关闭接口文档。

这个应该怎么做呢?

这里涉及到SpringBoot多环境配置，忘记的小伙伴可以翻一翻之前的文章。传送门:

我们创建三个配置文件，分别为。

① application-dev.yml 开发环境。
② application-test.yml 测试环境。
③ application-prod.yml 生产环境。

只需在①和②配置文件中添加如下配置。

springdoc:
  api-docs:
    enabled: true

而③配置文件中添加。

springdoc:
  api-docs:
    enabled: false

通过上面配置后，我们在开发和测试环境下：就能正常访问http://localhost:8080/v3/swagger-ui/index.html#/ 。

而在生产环境下就无法访问，报如下错误。

生产环境

5.5 配置API分组

为了演示API分组，我们在controller包下面再建立admin包和common包，包下分别添加AdminController和CommonController接口类,结构及代码如下。

包结构

① AdminController类。

// AdminController
@RestController
@RequestMapping("/admin")
public class AdminController {

    @GetMapping("/index")
    public String  admin(){
        return "admin";
    }
}

② CommonController 类。

@RestController
@RequestMapping("/common")
public class CommonController {

   @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

在默认情况（没有分组）的情况下，所有包下接口都显示在一一个默认组下面，如/common/* 和/admin/* 访问路径下的接口都显示在一起，如下图所示。

默认分组

这时，如果/common/* 下的接口比较多，/admin/* 下的接口也比较多，界面上显示就很混乱。

解决办法就是添加分组信息，我们在SpringDocConfig 配置类中添加如下代码,这样就把接口分为了"common通用模块组" 和"admin模块组" 两个组。

@Bean("commonGroupApi")
public GroupedOpenApi webGroupApi() {
    return GroupedOpenApi.builder().group("common通用模块组")
        .pathsToMatch("/common/**")
        .build();
}

@Bean("adminGroupApi")
public GroupedOpenApi adminGroupApi() {
    return GroupedOpenApi.builder().group("admin模块组")
        .pathsToMatch("/admin/**")
        .build();
}

重启服务，再访问http://localhost:8080/v3/swagger-ui/index.html 如下。

API分组

5.6 配置接口信息

① @Tag 注解使用。

对一个 operation 进行说明或定义的标签，用在类或方法上，也可以用在 @OpenAPIDefinition 中定义标签.

常用参数:

name: 名称
description: 接口描述信息

示例:

用在类上。

@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {
    //......
}

② @Operation 注解使用。

用于说明方法用途，用在方法上.

参数:

summary：方法概要，方法的一个简单介绍，建议 120 个字符内
description：方法描述，一般是很长的内容
hidden：是否隐藏

示例:

@GetMapping("/hello")
@Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
public String hello(){
    return "hello";
}

③ @Parameter注解使用。

用于说明方法参数，用在方法参数上.

参数:

name：指定的参数名
in：参数位置，可选 query、header、path 或 cookie，默认为空，表示忽略
description：参数描述
required：是否必填，默认为 false

示例:

@GetMapping("/user/{id}")
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用户ID",required = true) @PathVariable("id") Integer id){
    User user = userService.getUserById(id);
    return user;
}

前端页面查看。

@Paramter注解配置信息

④ @ApiResponse 注解使用。

用于说明一个响应信息，用在 @ApiResponses 中.

参数:

responseCode：HTTP 响应码
description：描述

示例:

@GetMapping("/user/{id}")
@Operation(summary = "获取用户信息", description = "根据用户ID获取用户信息")
@ApiResponses(value ={
    @ApiResponse(responseCode = "200", description = "请求成功"),
    @ApiResponse(responseCode = "404", description = "用户不存在")            
})
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用户ID",required = true) @PathVariable("id") Integer id){
    User user = userService.getUserById(id);
    return user;
}

@ApiResponse注解配置信息

完整配置。

@RestController
@RequestMapping("/common")
@Tag(name = "公共接口", description = "公共接口")
public class CommonController {

    @Autowired
    private IUserService userService;

   @GetMapping("/hello")
   @Operation(summary = "hello接口", description = "hello接口描述" ,hidden = true)
    public String hello(){
        return "hello";
    }

    @GetMapping("/hi")

    @Operation(summary = "hi接口", description = "hi接口描述")
    public String Hi(){
        return "Hi 程序员小凡";
    }

    @GetMapping("/user/{id}")
    @Operation(summary = "获取用户信息", description = "根据用户ID获取用户信息")
    @ApiResponses(value ={
            @ApiResponse(responseCode = "200", description = "请求成功"),
            @ApiResponse(responseCode = "404", description = "用户不存在")
    })
    public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用户ID",required = true) @PathVariable("id") Integer id){
        User user = userService.getUserById(id);
        return user;
    }
}

重启后，浏览器访问http://localhost:8080/v3/swagger-ui/index.html 如下。

5.7 配置实体信息

① 新建一个User实体类。

@Data
public class User {
    private String name;
    private Integer age;
    private String email;
    private String address;
}

② @Schema标签使用。

用于描述数据对象信息或数据对象属性，比如各种POJO类及属性，用在类或类属性上.

参数:

name：属性名称
description：属性描述
required：是否必须
minLength：字符最小长度
maxLength：字符最大长度

③使用示例:

@Data
@Schema(description = "用户实体类",name = "User")
public class User {
    @Schema(description = "用户名",name =  "name",minLength =  6,maxLength = 20,required = true)
    private String name;
    @Schema(description = "年龄",name =  "age",required = true,minimum = "1",maximum = "100")
    private Integer age;
    @Schema(description = "邮箱",name =  "email",required = true)
    private String email;
    @Schema(description = "地址",name =  "address")
    private String address;
}

④ 浏览器访问：http://localhost:8080/v3/swagger-ui/index.html ，我们看到配置的实体信息显示出来了。

实体信息

六、接口调试

通过上面各种配置之后，我们的在线接口文档基本上生成得差不多了。接下来我们就来说说怎么使用在线接口文档进行接口测试。

① 测试说明。

在之前小节中我们开发了要给根据用户ID 获取用户信息的接口getUser。我们现在要做的就是在前端UI界面中找到这个接口，。

在开发环境下输入用户ID值，然后获取用户信息.

② 选择组信息。

【获取用户信息】这个接口在，common通用模块组下面，所以我们第一步就要前端UI界面右上角选择这个组。

选择common通用模块组

② 选择开发环境。

在Servers 下选择配置好的开发环境。

选择开发环境

③ 找到我们要测试的接口。

找到目标接口

④ 测试接口，获取响应数据。

接口右边下三角箭头展开接口------>点击Try it out 。

点击Try it out

输入参数：用户ID------> 点击【Execute】----->在Response body 中查看接口响应信息。

根据用户id获取到响应信息

七、添加请求头

很多时候我们接口都需要认证之后才能访问，这时候我们就需要接口调用的时候携带着Token信息。

示例:

我们通过@RequestHeader 注解获取请求头中token信息。

@GetMapping("/index")
public String  admin(@RequestHeader ("token") String token){
	System.out.println("token>>>>>>>>>>>>>>>>>>>>>>>>"+token);
    //token 验证
    //.....各种业务逻辑
    return "admin";
}

添加请求头信息

到此，本期内容就结束了，★,°:.☆(￣▽￣)/$:.°★ 。希望对您有所帮助。

我们下期再见ヾ(•ω•`)o (●'◡'●) 。

最后此篇关于SpringBoot3整合SpringDoc实现在线接口文档的文章就讲到这里了,如果你想了解更多关于SpringBoot3整合SpringDoc实现在线接口文档的内容请搜索CFSDN的文章或继续浏览相关文章，希望大家以后支持我的博客！。

文章推荐： MinIO图片转文件的分界线RELEASE.2022-05-26T05-48-41Z

文章推荐： AgileConfig-1.9.4发布，支持OpenTelemetry

文章推荐：欢迎StableDiffusion3加入Diffusers

java - 自定义 JPA 实现//现有的无 SQL JPA 实现
背景: 我最近一直在使用 JPA，我为相当大的关系数据库项目生成持久层的轻松程度给我留下了深刻的印象。我们公司使用大量非 SQL 数据库，特别是面向列的数据库。我对可能对这些数据库使用 JPA 有一
java - 未由 S3FileSystem FileSystem 实现 Hadoop Jar 实现
我已经在我的 maven pom 中添加了这些构建配置，因为我希望将 Apache Solr 依赖项与 Jar 捆绑在一起。否则我得到了 SolarServerException: ClassNotF
c# - 实现 "Inherit"(实现)通用接口(interface)的接口(interface)？
interface ITurtle { void Fight(); void EatPizza(); } interface ILeonardo : ITurtle {
java - 任何 JPA 实现(或更广泛的 Java ORM 实现)是否支持可更新游标
我希望可用于 Java 的对象/关系映射 (ORM) 工具之一能够满足这些要求: 使用 JPA 或 native SQL 查询获取大量行并将其作为实体对象返回。允许在行(实体)中进行迭代，并在对当前
generics - 如果我为 B 实现 From ，是否也会为 Vec 实现 From>？
好像没有，因为我有实现From for 的代码, 我可以转换 A到 B与 .into() , 但同样的事情不适用于 Vec .into()一个Vec . 要么我搞砸了阻止实现派生的事情，要么这不应该发

c# - 在 C# 中，如果 A 实现 IX 并且 B 继承自 A ，是否必然遵循 B 实现 IX？
在 C# 中，如果 A 实现 IX 并且 B 继承自 A ，是否必然遵循 B 实现 IX？如果是，是因为 LSP 吗？之间有什么区别吗: 1. Interface IX; Class A : IX;

OpenVG 实现？
就目前而言，这个问题不适合我们的问答形式。我们希望答案得到事实、引用资料或专业知识的支持，但这个问题可能会引发辩论、争论、投票或扩展讨论。如果您觉得这个问题可以改进并可能重新打开，visit the

performance - 实现 (^)
我正在阅读标准haskell库的(^)的实现代码: (^) :: (Num a, Integral b) => a -> b -> a x0 ^ y0 | y0 a -> b ->a expo x0

博弈树的C++实现
我将把国际象棋游戏表示为 C++ 结构。我认为，最好的选择是树结构(因为在每个深度我们都有几个可能的移动)。这是一个好的方法吗？ struct TreeElement{ SomeMoveType

字符串匹配alg的c++实现
我正在为用户名数据库实现字符串匹配算法。我的方法采用现有的用户名数据库和用户想要的新用户名，然后检查用户名是否已被占用。如果采用该方法，则该方法应该返回带有数据库中未采用的数字的用户名。例子: “贾

图算法的C++实现
我正在尝试实现 Breadth-first search algorithm , 为了找到两个顶点之间的最短距离。我开发了一个 Queue 对象来保存和检索对象，并且我有一个二维数组来保存两个给定顶点

Python A* 实现
我目前正在 ika 中开发我的 Python 游戏，它使用 python 2.5 我决定为 AI 使用 A* 寻路。然而，我发现它对我的需要来说太慢了(3-4 个敌人可能会落后于游戏，但我想供应 4-

DHT的C++实现
我正在寻找 Kademlia 的开源实现C/C++ 中的分布式哈希表。它必须是轻量级和跨平台的(win/linux/mac)。它必须能够将信息发布到 DHT 并检索它。最佳答案 OpenDHT是

C++实现
我在一本书中读到这一行:-“当我们要求 C++ 实现运行程序时，它会通过调用此函数来实现。” 而且我想知道“C++ 实现”是什么意思或具体是什么。帮忙!？最佳答案 “C++ 实现”是指编译器加上链接

背包分支定界的C++实现
我正在尝试使用分支定界的 C++ 实现这个背包问题。此网站上有一个 Java 版本:Implementing branch and bound for knapsack 我试图让我的 C++ 版本打印

FNV哈希的C#实现
在很多情况下，我需要在 C# 中访问合适的哈希算法，从重写 GetHashCode 到对数据执行快速比较/查找。我发现 FNV 哈希是一种非常简单/好/快速的哈希算法。但是，我从未见过 C# 实现的

LRU缓存替换策略及C#实现
目录 LRU缓存替换策略核心思想不适用场景算法基本实现算法优化

大角度非迭代的空间坐标旋转C#实现
1. 绪论在前面文章中提到空间直角坐标系相互转换，测绘坐标转换时，一般涉及到的情况是：两个直角坐标系的小角度转换。这个就是我们经常在测绘数据处理中，WGS-84坐标系、54北京坐标系

实现.Net7下的数据库定时检查
在软件开发过程中，有时候我们需要定时地检查数据库中的数据，并在发现新增数据时触发一个动作。为了实现这个需求，我们在 .Net 7 下进行一次简单的演示. PeriodicTimer .

查找算法之二分查找的C++实现
二分查找二分查找算法，说白了就是在有序的数组里面给予一个存在数组里面的值key，然后将其先和数组中间的比较，如果key大于中间值，进行下一次mid后面的比较，直到找到相等的，就可以得到它的位置。

撒哈拉

个人简介
我是一名优秀的程序员,十分优秀！

作者热门文章

VisualStudio2022插件的安装及使用-编程手把手系列文章

pprof-在现网场景怎么用

C#实现的下拉多选框，下拉多选树，多级节点

【学习笔记】基础数据结构：猫树

滴滴打车优惠券免费领取

全站热门文章

OpenCL入门笔记

深入解析SpringAI系列：以OpenAI与Moonshot案例为例寻找共同点

探索自联接（SELFJOIN）：揭示数据间复杂关系的强大工具

20250110-FortuneWheel攻击事件：竟然不设滑点，那就体验一下ForceInvestment吧

G1原理—3.G1是如何提升垃圾回收效率

Java实现任务管理器性能网络监控数据

详解：订单履约系统规划

外部H5唤起常用小程序链接规则整理

[.NET]使用客户端缓存提高API性能

WPF怎么利用behavior优雅的给一个Datagrid添加一个全选的功能

首页

博学

6Ren·AI

商城