首页
/ 正文

springboot swagger（保姆级教程）

更新时间: 2025-03-17 16:59:05

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;

《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前，星球内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习，欢迎点击围观

在现代 Web 开发中，API 的设计与测试是项目落地的核心环节之一。对于开发者而言，如何高效地管理、调试和展示 API 文档始终是一个挑战。Spring Boot 作为 Java 生态中广受欢迎的微服务框架，其简洁的开发模式和强大的插件生态，为这一问题提供了理想的解决方案。而 Swagger（现称为 OpenAPI）作为 API 文档生成与测试工具，与 Spring Boot 的结合，能够显著提升开发效率，降低维护成本。

本文将从零开始，逐步讲解如何在 Spring Boot 项目中集成 Swagger，并通过实际案例和代码示例，深入剖析其核心功能与最佳实践。无论你是刚接触后端开发的初学者，还是希望优化现有项目架构的中级开发者，都能从中获得实用的知识与灵感。

一、Spring Boot 与 Swagger 的协同价值

1.1 为什么需要 Swagger？

想象一下，当你需要向同事或第三方开发者展示 API 接口时，传统的文档方式（如 Word 或 Markdown 文件）往往存在以下痛点：

维护成本高：接口变更后需要手动更新文档，容易出现版本不一致。
交互性差：开发者无法直接通过文档进行调用测试，调试效率低下。
信息不完整：文档可能遗漏参数说明、响应示例或错误码等关键信息。

而 Swagger 通过自动化生成 API 文档，解决了这些问题。它提供了一套规范化的接口描述语言（OpenAPI Specification），并配套了可视化工具（如 Swagger UI），允许开发者：

实时同步文档与代码：文档内容直接与代码中的注解绑定，修改接口时文档自动更新。
在线测试接口：无需编写额外测试代码，即可在网页界面直接调用接口并查看响应。
标准化接口定义：通过统一的注解规范，提升团队协作的规范性与一致性。

1.2 Spring Boot 的天然适配性

Spring Boot 的“约定优于配置”原则，使其与 Swagger 的集成变得简单高效。通过添加依赖和少量配置，即可快速启动完整的 API 文档系统。这种设计不仅降低了学习门槛，还避免了复杂的 XML 配置，符合现代开发者追求极简开发体验的需求。

二、快速上手：在 Spring Boot 中集成 Swagger

2.1 环境准备

2.1.1 项目基础配置

假设你已有一个 Spring Boot 项目（版本建议 2.7.x 或更高），在 pom.xml 中添加以下依赖：

<!-- Swagger 核心依赖 -->  
<dependency>  
    <groupId>io.springfox</groupId>  
    <artifactId>springfox-boot-starter</artifactId>  
    <version>3.0.0</version>  
</dependency>

注意：若使用 Spring Boot 3.x，需改用 springdoc-openapi-starter-webmvc-ui，因为 SpringFox 已停止维护。

2.1.2 启动类配置

在主启动类或独立的配置类中，通过 @EnableOpenApi 注解启用 Swagger：

import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.Configuration;  
import io.springfox.oas.annotations.OpenAPIDefinition;  
import io.springfox.oas.annotations.info.Info;  

@Configuration  
@EnableOpenApi  
public class SwaggerConfig {  
    @Bean  
    public OpenAPI customOpenAPI() {  
        return new OpenAPI()  
            .info(new Info().title("My API Documentation")  
                          .description("This is a sample API for learning purposes")  
                          .version("1.0.0"));  
    }  
}

此时，访问 http://localhost:8080/swagger-ui/index.html，即可看到默认的文档界面。

三、核心注解与文档编写

3.1 基础注解详解

Swagger 的核心在于通过注解描述接口的元数据。以下是一些常用注解及其作用：

注解名	作用说明
`@Operation`	描述单个接口的功能、参数、返回值及权限等。
`@Parameter`	标注路径参数、查询参数或请求体参数的详细信息。
`@ApiResponse`	定义接口可能返回的 HTTP 状态码及响应体结构。
`@Schema`	描述复杂对象（如 DTO）的字段类型、格式及约束。

3.1.1 示例：一个简单的 GET 接口

@RestController  
@RequestMapping("/api/users")  
public class UserController {  
    @GetMapping("/{id}")  
    @Operation(  
        summary = "获取用户信息",  
        description = "根据用户 ID 查询用户详细信息",  
        responses = {  
            @ApiResponse(  
                responseCode = "200",  
                description = "用户信息返回成功",  
                content = @Content(  
                    schema = @Schema(implementation = User.class)  
                )  
            ),  
            @ApiResponse(  
                responseCode = "404",  
                description = "用户不存在"  
            )  
        }  
    )  
    public User getUserById(@Parameter(description = "用户唯一标识符") @PathVariable Long id) {  
        // 实现逻辑  
    }  
}

解释：

@Operation 提供接口的标题、描述及响应状态码说明。
@Parameter 为路径变量 id 添加描述，帮助使用者理解参数含义。
@Schema 指定返回对象的类型（此处为 User 类），Swagger 会自动生成字段结构图。

3.2 进阶技巧：请求体与响应示例

对于 POST/PUT 等需要请求体的接口，可以通过 @RequestBody 和 @ExampleObject 提供示例数据：

@PostMapping  
@Operation(  
    summary = "创建新用户",  
    requestBody = @RequestBody(content = @Content(  
        examples = {  
            @ExampleObject(  
                value = "{ \"name\": \"张三\", \"email\": \"zhangsan@example.com\" }"  
            )  
        }  
    ))  
)  
public User createUser(@RequestBody User user) {  
    // 实现逻辑  
}

此时，在 Swagger UI 的请求体输入框中，会直接展示示例 JSON，减少使用者的试错成本。

四、高级功能与优化策略

4.1 文档分组与权限控制

4.1.1 按模块分组

当项目接口较多时，可通过 tags 参数将接口划分为不同组：

@Operation(  
    tags = {"用户管理"},  
    summary = "删除用户"  
)  
@DeleteMapping("/{id}")  
public ResponseEntity<String> deleteUser(@PathVariable Long id) {  
    // 实现逻辑  
}

在 Swagger UI 中，这些接口会自动归类到“用户管理”标签下，提升文档可读性。

4.1.2 集成安全认证

若接口需要 OAuth2 或 API Key 认证，可通过 @SecurityScheme 注解定义认证方式：

@Configuration  
public class SecurityConfig {  
    @Bean  
    public OpenAPI customOpenAPI() {  
        return new OpenAPI()  
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))  
            .components(new Components().addSecuritySchemes(  
                "bearerAuth",  
                new SecurityScheme()  
                    .name("bearerAuth")  
                    .type(SecurityScheme.Type.HTTP)  
                    .scheme("bearer")  
                    .bearerFormat("JWT")  
            ));  
    }  
}

这样，调用接口时，Swagger UI 会提示用户输入 Token，确保测试环境的安全性。

4.2 性能优化与配置调整

4.2.1 排除敏感接口

默认情况下，Swagger 会扫描所有 @RestController 中的接口。可通过 @Hidden 注解或配置过滤器，隐藏内部或测试接口：

@Hidden  
@GetMapping("/internal/health-check")  
public String healthCheck() {  
    return "OK";  
}

4.2.2 自定义 UI 样式

通过修改 swagger-ui.css 或通过配置项调整主题：

@Configuration  
public class SwaggerConfig {  
    @Bean  
    public UiConfiguration uiConfig() {  
        return UiConfigurationBuilder.builder()  
            .deepLinking(true)  
            .defaultModelsExpandDepth(-1)  
            .validatorUrl("null") // 禁用 OpenAPI 规范校验  
            .build();  
    }  
}

五、实际案例：一个完整的 REST API 文档

5.1 场景描述

假设我们正在开发一个书籍管理 API，包含以下功能：

查询书籍列表（GET /api/books）
根据 ID 查询单本书籍（GET /api/books/{id}）
新增书籍（POST /api/books）

5.2 完整代码实现

5.2.1 实体类与接口定义

// 实体类  
@Data  
public class Book {  
    private Long id;  
    @Schema(description = "书籍标题", example = "Spring Boot实战")  
    private String title;  
    @Schema(description = "作者姓名", example = "张三")  
    private String author;  
    @Schema(description = "出版年份", example = "2023")  
    private Integer year;  
}  

// 控制器  
@RestController  
@RequestMapping("/api/books")  
public class BookController {  
    @GetMapping  
    @Operation(  
        summary = "获取书籍列表",  
        description = "支持通过查询参数过滤书籍"  
    )  
    public List<Book> getAllBooks(  
        @Parameter(description = "书籍标题关键字") @RequestParam(required = false) String keyword,  
        @Parameter(description = "分页起始位置") @RequestParam(defaultValue = "0") Integer page  
    ) {  
        // 实现逻辑  
    }  

    @PostMapping  
    @Operation(  
        summary = "创建新书籍",  
        description = "需要提供书籍标题、作者和出版年份"  
    )  
    public Book createBook(@RequestBody @Valid Book book) {  
        // 实现逻辑  
    }  
}

5.2.2 运行效果

完成上述代码后，启动项目并访问 http://localhost:8080/swagger-ui/index.html，可以看到如下界面：

书籍列表接口：支持输入 keyword 和 page 参数，返回书籍列表的示例数据。
创建书籍接口：提供请求体的 JSON 示例，并展示成功（201）与失败（400）的响应示例。

六、总结与展望

通过本文的讲解，我们已经掌握了 Spring Boot 与 Swagger 的深度整合，从基础集成到高级配置，再到实际案例的落地。以下是关键知识点的回顾：

快速集成：通过依赖管理和简单注解，即可启动文档系统。
注解驱动开发：使用 @Operation、@Parameter 等注解，确保文档与代码的一致性。
增强可维护性：通过分组、示例和安全配置，提升文档的实用性和安全性。

对于开发者而言，Swagger 不仅是一个工具，更是一种 API 设计的最佳实践。随着项目复杂度的提升，建议进一步探索以下方向：

自动化测试：结合 Postman 或 JUnit，基于 Swagger 文档生成测试用例。
版本控制：通过 OpenAPI 规范文件（如 openapi.yaml），实现 API 版本的回溯与兼容性管理。
团队协作：将文档链接共享给前端团队，确保前后端接口定义的完全一致。

希望本文能为你带来启发，让你在 API 开发的道路上走得更稳、更快！