SpringBoot+Swagger打造美观API文档的实战指南

更新时间：2025年08月12日 09:12:03 作者：樽酒ﻬق

在现代 Web 开发中,API 文档是开发者和团队协作的重要组成部分,本文将详细介绍如何在 SpringBoot2和SpringBoot3中集成Swagger,并展示多种接口文档风格,帮助开发者选择适合自己项目的展示方式

导语

在现代 Web 开发中，API 文档是开发者和团队协作的重要组成部分。Swagger 作为一款强大的 API 文档生成工具，能够自动生成直观、可交互的接口文档，提升开发效率。本文将详细介绍如何在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger，并展示多种接口文档风格，帮助开发者选择适合自己项目的展示方式。

一、Swagger 简介

Swagger 是一个开源工具，用于生成、描述和可视化 RESTful API。它不仅能自动生成 API 文档，还提供交互式界面，方便开发者测试和调试接口。Swagger 与 Spring Boot 集成后，可以轻松管理和展示项目的 API。

二、Spring Boot 2 集成 Swagger

Spring Boot 2 中，常用的 Swagger 集成方案是基于 Springfox 库。以下是具体步骤：

1. 添加依赖

在项目的 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 配置 Swagger

创建一个配置类，例如 SwaggerConfig.java，启用 Swagger 并定义文档的基本信息：

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定扫描的包
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 2 Swagger API")
                .description("API documentation for Spring Boot 2 project")
                .version("1.0.0")
                .build();
    }
}

3. 访问 Swagger UI

启动 Spring Boot 应用后，打开浏览器访问 http://localhost:8080/swagger-ui.html，即可看到生成的 API 文档界面。

三、Spring Boot 3 集成 Swagger

Spring Boot 3 中，由于 Springfox 已不再积极维护，推荐使用 Springdoc OpenAPI 库。它与 Spring Boot 3 的新特性（如 Jakarta EE）兼容，且配置更简单。

1. 添加依赖

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

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>

2. 配置 Swagger

Springdoc 默认自动启用 Swagger UI，无需额外配置。但可以通过 application.properties 或 application.yml 自定义路径和行为，例如：

# 自定义 Swagger UI 路径
springdoc.swagger-ui.path=/swagger-ui.html
# 自定义 API 文档 JSON 路径
springdoc.api-docs.path=/v3/api-docs

3. 访问 Swagger UI

启动应用后，访问 http://localhost:8080/swagger-ui.html，即可查看 API 文档。

四、多种接口文档风格展示

Swagger 提供了多种 UI 风格，开发者可以根据需求选择合适的展示方式。以下是几种常见的风格及其配置方法：

1. 默认 Swagger UI

Swagger UI 是最常用的风格，提供交互式界面，支持 API 测试。Spring Boot 2 和 3 默认集成后即可使用：

Spring Boot 2：http://localhost:8080/swagger-ui.html
Spring Boot 3：http://localhost:8080/swagger-ui.html

2. Redoc

Redoc 是一个简洁、美观的静态文档展示工具，适合生成静态 API 文档。在 Spring Boot 3 中使用 Springdoc 配置：

在 application.properties 中添加：

# 禁用默认 Swagger UI
springdoc.swagger-ui.enabled=false
# 启用 Redoc
springdoc.redoc.enabled=true

访问 http://localhost:8080/redoc，即可查看 Redoc 风格的文档。

3. Knife4j

Knife4j 是 Swagger 的增强版，提供更丰富的功能和更友好的界面，支持 Spring Boot 2 和 3。

在 Spring Boot 2 中集成 Knife4j

添加依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

修改配置类：

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 2 Knife4j API")
                .description("API documentation with Knife4j")
                .version("1.0.0")
                .build();
    }
}

访问 http://localhost:8080/doc.html，即可体验 Knife4j 界面。

在 Spring Boot 3 中集成 Knife4j

添加依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

无需额外配置，启动应用后访问 http://localhost:8080/doc.html。

五、实战示例

以下是一个简单的 Spring Boot 项目示例，展示如何使用 Swagger 注解生成详细的 API 文档。

1. 创建控制器

创建一个简单的 REST 控制器：

import org.springframework.web.bind.annotation.*;
import java.util.*;

@RestController
@RequestMapping("/api")
public class UserController {
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

2. 添加 Swagger 注解

为控制器和方法添加注解，提供更详细的 API 描述：

Spring Boot 2（Springfox）

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@Api(tags = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
    @ApiOperation(value = "获取所有用户", notes = "返回用户列表")
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @ApiOperation(value = "创建新用户", notes = "创建并返回新用户")
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

Spring Boot 3（Springdoc）

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@Tag(name = "User API")
@RestController
@RequestMapping("/api")
public class UserController {
    @Operation(summary = "获取所有用户", description = "返回用户列表")
    @GetMapping("/users")
    public List<String> getUsers() {
        return Arrays.asList("Alice", "Bob");
    }

    @Operation(summary = "创建新用户", description = "创建并返回新用户")
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "Created: " + user;
    }
}

3. 访问和测试

启动应用后，访问对应的 Swagger UI 或 Knife4j 地址（如 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/doc.html），即可查看并测试 API。

六、总结

本文介绍了在 Spring Boot 2 和 Spring Boot 3 中集成 Swagger 的实战步骤：

Spring Boot 2 使用 Springfox Swagger，配置简单但维护较少。
Spring Boot 3 推荐 Springdoc OpenAPI，与新版本兼容且功能强大。

同时展示了多种接口文档风格：

Swagger UI：交互性强，适合开发和调试。
Redoc：简洁美观，适合静态文档。
Knife4j：功能丰富，体验更优。

通过实战示例，开发者可以快速上手并将 Swagger 应用到自己的项目中，提升 API 管理的效率和质量。

到此这篇关于SpringBoot+Swagger打造美观API文档的实战指南的文章就介绍到这了,更多相关SpringBoot Swagger构建API文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

Javaweb使用getPart接收表单文件过程解析
这篇文章主要介绍了Javaweb使用getPart接收表单文件过程解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-07-07
微服务如何通过feign.RequestInterceptor传递参数
这篇文章主要介绍了微服务如何通过feign.RequestInterceptor传递参数，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-03-03
Spring中@EnableScheduling实现定时任务代码实例
这篇文章主要介绍了Spring中@EnableScheduling实现定时任务代码实例,@EnableScheduling 注解开启定时任务功能,可以将多个方法写在一个类,也可以分多个类写,当然也可以将方法直接写在上面ScheddulConfig类中,需要的朋友可以参考下
2024-01-01
java多线程数据分页处理实例讲解
在本篇内容里小编给大家分享了一篇关于java多线程数据分页处理实例讲解内容，有兴趣的朋友们可以学习下。
2021-01-01
java8、jdk8日期转化成字符串详解
在本篇文章中小编给大家整理了关于java8、jdk8日期转化成字符串的相关知识点和代码，需要的朋友们学习下。
2019-04-04
jar包运行时提示jar中没有主清单属性的解决
这篇文章主要介绍了jar包运行时提示jar中没有主清单属性的解决方案，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2023-02-02
SpringBoot实现优雅停机的正确方法
什么叫优雅停机？就是向应用进程发出停止指令之后，能保证正在执行的业务操作不受影响，直到操作运行完毕之后再停止服务。本文就来和大家聊聊SpringBoot实现优雅停机的正确姿势，希望对大家有所帮助
2023-01-01
JavaMail整合Spring实现邮件发送功能
这篇文章主要为大家详细介绍了JavaMail整合Spring实现邮件发送功能，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2022-08-08
postman 如何实现传递 ArrayList 给后台
这篇文章主要介绍了postman 如何实现传递 ArrayList给后台，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-12-12
Java高效实现excel转pdf(支持带图片的转换)
这篇文章主要为大家详细介绍了如何用java实现excel转pdf文件,并且支持excel单元格中带有图片的转换,文中的示例代码讲解详细,需要的可以参考下
2024-01-01