SpringBoot3.4.3基于SpringDoc2和Swagger3实现项目接口文档管理

itbeien2025年3月3日大约 11 分钟

SpringBoot3.4.3基于SpringDoc2和Swagger3实现项目接口文档管理

本专栏前一篇文章SpringBoot3.4.3基于Spring WebFlux实现SSE功能。今天分享SpringBoot3.4.3基于SpringDoc2和Swagger3实现项目接口文档管理功能，开发者可以基于OpenAPI3标准使用 Swagger3 为你的企业级应用构建一套高标准化接口文档。

完整代码在文章最后，如果觉得本篇文章对你有用，记得点赞、关注、收藏哦。你的支持是我持续更新的动力!

文章最后可以加入免费的Java&AI技术和支付系统沟通社群，一起探讨Java/你的产品如何与AI结合，请按照要求加入。在群中可以聊开发、系统设计、架构、行业趋势、AI等等话题

SpringBoot3专栏软件环境

JDK17.0.12
SpringBoot3.4.3
IDEA2024.3.3
SpringDoc2.8.5

我们先看本篇文章对应的项目结构，请看下图

Github:https://github.com/springdoc/springdoc-openapi

1 什么是SpringDoc2

SpringDoc 2 是一个基于 Spring 框架构建的开源库，主要用于根据 Spring 应用中的代码自动生成符合 OpenAPI 3.0 及以上规范的 API 文档。它能帮助开发者更轻松地创建、维护和展示 RESTful API 的详细信息，让 API 的使用者（如前端开发人员、测试人员等）能够清晰地了解 API 的功能、参数、返回值等。

1.1 特点

自动生成文档：SpringDoc 2 可以扫描 Spring 项目中的控制器类、方法以及相关注解，自动生成 OpenAPI 规范的 API 文档。无需开发者手动编写大量的文档，减少了文档编写的工作量和出错概率。
支持多种 Spring 编程模型：无论是基于注解的 Spring MVC 编程模型，还是响应式的 Spring WebFlux 编程模型，SpringDoc 2 都能很好地支持，具有广泛的适用性。
集成 Swagger UI：它能够与 Swagger UI 集成，将生成的 OpenAPI 文档以可视化的方式展示出来。开发者和 API 使用者可以通过浏览器访问 Swagger UI 界面，直观地查看 API 的详细信息，并可以直接在界面上进行 API 请求测试。
注解驱动：提供了丰富的注解，如 @Operation、@ApiResponse 等，开发者可以使用这些注解来进一步丰富 API 文档的信息，包括接口的描述、请求参数说明、响应状态码含义等。
高度可配置：可以通过配置文件（如 application.properties 或 application.yml）对生成的文档进行定制，例如设置文档的标题、描述、版本号，以及控制哪些接口需要生成文档等。

1.2 使用场景

内部项目开发：在团队内部的项目开发中，SpringDoc 2 可以帮助前后端开发人员更好地协作。前端开发人员可以根据生成的 API 文档了解后端接口的详细信息，从而更高效地进行前端页面的开发。
对外提供 API 服务：当企业或组织对外提供 API 服务时，SpringDoc 2 生成的详细 API 文档可以作为开发者文档，方便外部开发者快速了解和使用 API，提高 API 的可访问性和易用性。
API 测试：测试人员可以利用 Swagger UI 界面直接对 API 进行测试，验证接口的功能和正确性，减少编写测试代码的工作量。

1.3 与其他工具的关系

与 OpenAPI 规范：SpringDoc 2 严格遵循 OpenAPI 3.0 及以上规范，生成的 API 文档具有良好的兼容性和互操作性，可以被其他支持 OpenAPI 规范的工具（如 Postman、Apifox 等）识别和使用。
与 Swagger 的关系：Swagger 是一个围绕 OpenAPI 规范发展起来的工具集，SpringDoc 2 集成了 Swagger UI 来展示 API 文档，从功能和使用场景上可以看作是在 Spring 项目中实现 Swagger 相关功能的一种方式，并且对 OpenAPI 规范的支持更加完善。

2 什么是Swagger3

Swagger 是一个独立的开源项目，后来 OpenAPI 规范从 Swagger 规范发展而来。Swagger 3 可以理解为围绕 OpenAPI 3.0 规范构建的一套工具和解决方案，用于帮助开发者更高效地设计、构建、文档化和使用 RESTful API。

2.1 核心组件

Swagger Editor：这是一个基于 Web 的编辑器，支持使用 YAML 或 JSON 格式编写 OpenAPI 规范文档。它提供了实时预览和验证功能，开发者可以在编写过程中及时发现和纠正错误，确保 API 定义的准确性。
Swagger UI：是一个可视化的界面工具，能够将 OpenAPI 规范文档以直观的方式展示出来。通过 Swagger UI，开发者和 API 使用者可以方便地查看 API 的详细信息，包括接口的描述、请求参数、响应格式等，还可以直接在界面上进行 API 请求测试。
Swagger Codegen：可以根据 OpenAPI 规范文档自动生成客户端 SDK 和服务器端代码。支持多种编程语言和框架，如 Java、Python、JavaScript 等，大大减少了开发者手动编写代码的工作量。

2.2 特点

遵循 OpenAPI 3.0 规范：OpenAPI 3.0 规范在数据类型、请求体和响应体的定义、安全机制等方面进行了改进和扩展。Swagger 3 充分利用了这些新特性，能够更准确地描述 API 的功能和结构。
增强的安全性支持：支持多种安全认证方式，如 OAuth 2.0、API 密钥、HTTP 基本认证等。开发者可以在 OpenAPI 文档中清晰地定义 API 的安全要求，并且 Swagger UI 会根据这些定义提供相应的认证接口。
更好的性能和可扩展性：在性能方面进行了优化，能够更快速地加载和展示 API 文档。同时，具有良好的可扩展性，支持与其他工具和框架集成，如 Spring、SpringBoot 等。
多语言支持：Swagger Codegen 支持生成多种编程语言的代码，方便不同技术栈的开发者使用。

2.3 使用场景

API 设计和文档化：在 API 开发的初期，开发者可以使用 Swagger Editor 设计 API 的结构和功能，并生成详细的 OpenAPI 规范文档。这个文档可以作为团队内部沟通的依据，也可以对外发布，供其他开发者参考。
API 测试：Swagger UI 提供了方便的测试界面，开发者和测试人员可以直接在界面上输入请求参数，发送请求并查看响应结果，快速验证 API 的正确性。
客户端和服务器端代码生成：使用 Swagger Codegen 可以根据 OpenAPI 文档自动生成客户端 SDK 和服务器端代码，提高开发效率，减少人为错误。

3 项目中使用SpringDoc2

3.1 pom依赖

<?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">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>cn.itbeien</groupId>
        <artifactId>springboot3-labs-master</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>

    <artifactId>springboot-springdoc2</artifactId>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <springdoc-openapi-starter-webmvc-ui-version>2.8.5</springdoc-openapi-starter-webmvc-ui-version>
    </properties>


    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>${springdoc-openapi-starter-webmvc-ui-version}</version>
        </dependency>
    </dependencies>

</project>

3.2 配置信息

package cn.itbeien.springdoc.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * @author itbeien
 * 项目网站：https://www.itbeien.cn
 * 公众号：贝恩聊架构
 * 全网同名，欢迎小伙伴们关注
 * Java/AI学习社群
 * Copyright© 2025 itbeien
 */
@Configuration
public class Swagger3Config {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("贝恩聊架构 Swagger3 详解")
                        .description("Swagger3 Spring Boot 3.4.3 application")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("https://www.itbeien.cn")))
                .externalDocs(new ExternalDocumentation()
                        .description("api接口文档")
                        .url("https://www.itbeien.cn"));
    }
}

3.3 Controller接口定义

package cn.itbeien.springdoc.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author itbeien
 * 项目网站：https://www.itbeien.cn
 * 公众号：贝恩聊架构
 * 全网同名，欢迎小伙伴们关注
 * Java/AI学习社群
 * 使用@Operation、@ApiResponses、@ApiResponse等注解来详细描述接口的功能、响应状态码和响应内容等信息
 * Copyright© 2025 itbeien
 */
@RestController
public class ApiController {

    @Operation(summary = "测试接口", description = "用于返回测试信息")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "返回信息成功",
                    content = {@Content(mediaType = "text/plain",
                            schema = @Schema(implementation = String.class))})
    })
    @GetMapping("/hello")
    public String hello() {
        return "Hello, Spring Boot 3 with SpringDoc 2";
    }
}

3.4 响应对象定义

package cn.itbeien.springdoc.vo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;
import lombok.Setter;

import java.io.Serializable;

/**
 * @author itbeien
 * 项目网站：https://www.itbeien.cn
 * 公众号：贝恩聊架构
 * 全网同名，欢迎小伙伴们关注
 * Java/AI学习社群
 * Copyright© 2025 itbeien
 */
@Setter
@Getter
@Schema(description = "响应对象")
public class Result <T> implements Serializable {

    @Schema(
            title = "code",
            description = "响应码",
            format = "int32",
            requiredMode = Schema.RequiredMode.REQUIRED
    )
    private Integer code;

    @Schema(
            title = "msg",
            description = "响应信息",
            accessMode = Schema.AccessMode.READ_ONLY,
            example = "成功或失败",
            requiredMode = Schema.RequiredMode.REQUIRED
    )
    private String message;

    @Schema(title = "data", description = "响应数据", accessMode = Schema.AccessMode.READ_ONLY)
    private T data;
}