Spring Boot 3.x 引入 Springdoc-OpenAPI（内置 Swagger UI、WebMVC-API）

一只蜗牛儿

于 2024-09-30 12:09:52 发布

阅读量320

点赞数 13

文章标签： spring boot ui 后端

本文链接：https://blog.csdn.net/qq_42978535/article/details/142653971

版权

Springdoc-OpenAPI 是一个用于在 Spring Boot 应用程序中自动生成 OpenAPI 文档的库，提供了集成 Swagger UI 的能力，可以帮助开发者快速实现 API 文档的生成和展示。在 Spring Boot 3.x 中，引入 Springdoc-OpenAPI 可以简化 RESTful API 的文档化过程。本文将介绍如何在 Spring Boot 3.x 项目中引入 Springdoc-OpenAPI，并配置 Swagger UI 进行 API 文档的展示。

一、项目准备

1.1 创建 Spring Boot 项目

可以使用 Spring Initializr （https://start.spring.io/）创建一个新的 Spring Boot 项目，选择以下依赖：

Spring Web
Spring Boot DevTools
Lombok（可选，简化 Java 代码）

1.2 添加 Springdoc-OpenAPI 依赖

在 pom.xml 中添加 Springdoc-OpenAPI 依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version> <!-- 请根据最新版本更新 -->
</dependency>

二、创建 RESTful API

2.1 创建 Controller

在 src/main/java/com/example/demo/controller 目录下创建 HelloController 类，示例代码如下：

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, Springdoc OpenAPI!";
    }
}

2.2 配置 API 文档信息

在 src/main/resources/application.yml 中，添加以下配置来设置 API 文档的基本信息：

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

三、运行项目

3.1 启动 Spring Boot 应用程序

使用 IDE 启动 Spring Boot 应用程序，或者在项目根目录下使用以下命令：

./mvnw spring-boot:run

3.2 访问 Swagger UI

打开浏览器，访问 http://localhost:8080/swagger-ui.html，你将看到自动生成的 API 文档页面，包含 /hello 接口的信息。

四、API 文档展示

在 Swagger UI 页面中，你可以看到如下内容：

API 端点：列出了所有可用的 API 端点。
请求方法：支持的请求方法（GET、POST 等）。
请求参数：如果有请求参数，将会列出。
响应信息：API 的响应信息和示例。

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

五、自定义 API 文档信息

5.1 使用注解丰富 API 文档

你可以使用 Springdoc 提供的注解来丰富 API 文档信息，如下所示：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

// ...

@RestController
public class HelloController {

    @Operation(summary = "Hello API", description = "返回一个问候消息")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功返回问候消息"),
        @ApiResponse(responseCode = "500", description = "内部服务器错误")
    })
    @GetMapping("/hello")
    public String hello() {
        return "Hello, Springdoc OpenAPI!";
    }
}

在以上代码中，我们使用了 @Operation 和 @ApiResponses 注解来描述 API 的功能和响应。

5.2 添加 API 分组

如果你的项目中有多个模块，可以使用 API 分组来组织文档：

import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "Hello API", description = "与问候相关的 API")
@RestController
public class HelloController {
    // ...
}