脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 软件编程 → java → SpringBoot Swagger构建API文档

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文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • Java的web开发中SSH框架的协作处理应用笔记

    Java的web开发中SSH框架的协作处理应用笔记

    这篇文章主要介绍了Java的web开发中SSH框架的协作处理应用笔记,SSH是指Struts和Spring以及Hibernate的框架搭配,需要的朋友可以参考下
    2015-12-12
  • Jenkins安装和插件管理配置入门教程

    Jenkins安装和插件管理配置入门教程

    这篇文章主要介绍了Jenkins安装和插件管理知识，本文通过图文并茂的形式给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2022-02-02
  • springboot整合shardingjdbc实现分库分表最简单demo

    springboot整合shardingjdbc实现分库分表最简单demo

    我们知道分库分表是针对某些数据量持续大幅增长的表，比如用户表、订单表等，而不是一刀切将全部表都做分片，这篇文章主要介绍了springboot整合shardingjdbc实现分库分表最简单demo,需要的朋友可以参考下
    2021-06-06
  • Java中初始化List的5种方法示例

    Java中初始化List的5种方法示例

    这篇文章主要给大家介绍了关于Java中初始化List的5种方法，文中通过示例代码介绍的非常详细，对大家学习或使用java具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2018-11-11
  • springMVC利用FastJson接口返回json数据相关配置详解

    springMVC利用FastJson接口返回json数据相关配置详解

    本篇文章主要介绍了springMVC利用FastJson接口返回json数据相关配置详解，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
    2017-06-06
  • Spring实战之Bean销毁之前的行为操作示例

    Spring实战之Bean销毁之前的行为操作示例

    这篇文章主要介绍了Spring实战之Bean销毁之前的行为操作,结合实例形式分析了spring在bean销毁之前的行为相关设置与使用技巧,需要的朋友可以参考下
    2019-11-11
  • Java读取图片EXIF信息的方法

    Java读取图片EXIF信息的方法

    这篇文章主要介绍了Java读取图片EXIF信息的方法,较为详细的分析了图片EXIF信息的概念、功能及java读取EXIF信息的实现技巧,需要的朋友可以参考下
    2015-07-07
  • Spring源码BeanFactoryPostProcessor详解

    Spring源码BeanFactoryPostProcessor详解

    BeanFactoryPostProcessor的执行时机是在Spring扫描完成后,Bean初始化前,当我们实现BeanFactoryPostProcessor接口,可以在Bean的初始化之前对Bean进行属性的修改，下面通过本文看下Spring源码分析-BeanFactoryPostProcessor的实例代码，感兴趣的朋友一起看看吧
    2021-11-11
  • java基于websocket实现im聊天功能

    java基于websocket实现im聊天功能

    这篇文章主要为大家介绍了java基于websocket实现im聊天功能示例详解,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2023-11-11
  • MyBatis 多表联合查询及优化方法

    MyBatis 多表联合查询及优化方法

    大家都知道Hibernate 是全自动的数据库持久层框架，它可以通过实体来映射数据库，通过设置一对多、多对一、一对一、多对多的关联来实现联合查询，接下来通过本文给大家介绍MyBatis 多表联合查询及优化,需要的朋友可以参考下
    2022-08-08

最新评论