API文档自动化：SpringBoot + Swagger3接口文档生成的10个技巧

已于 2025-03-03 13:22:57 修改
阅读量1.4k 收藏 24
点赞数 20
分类专栏： Web 文章标签： spring boot 自动化 后端
于 2025-03-03 09:52:17 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/ashyyyy/article/details/145976779
版权

🌟博主介绍：Java、Python、js全栈开发 “多面手”，精通多种编程语言和技术，痴迷于人工智能领域。秉持着对技术的热爱与执着，持续探索创新，愿在此分享交流和学习，与大家共进步。
📖全栈开发环境搭建运行攻略：多语言一站式指南(环境搭建+运行+调试+发布+保姆级详解)
👉感兴趣的可以先收藏起来，希望帮助更多的人
在这里插入图片描述

API文档自动化：SpringBoot + Swagger3接口文档生成的10个技巧

一、Swagger3简介

1.1 什么是Swagger3

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger3 是 Swagger 的升级版，它基于 OpenAPI 3.0 规范，提供了更强大的功能和更好的兼容性。

1.2 为什么选择Swagger3

  • 可视化界面：Swagger3 提供了一个直观的 UI 界面，方便开发人员和测试人员查看和测试 API。
  • 自动生成文档：只需在代码中添加少量注解，Swagger3 就能自动生成详细的 API 文档。
  • 支持多种格式：可以生成 JSON、YAML 等格式的文档，方便与其他系统集成。

二、SpringBoot集成Swagger3

2.1 添加依赖

在 pom.xml 中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.2 配置Swagger3

创建一个配置类，用于配置 Swagger3：

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

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot + Swagger3 API文档")
               .description("API文档详细描述")
               .version("1.0.0")
               .build();
    }
}

2.3 访问Swagger UI

启动 Spring Boot 应用程序，访问 http://localhost:8080/swagger-ui/index.html 即可看到 Swagger UI 界面。

三、使用注解增强API文档

3.1 @Api注解

@Api 注解用于标记控制器类，提供控制器的基本信息：

import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Tag(name = "用户管理", description = "用户管理相关接口")
public class UserController {
    // 控制器方法
}

3.2 @ApiOperation注解

@ApiOperation 注解用于标记控制器方法，提供方法的基本信息：

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/users")
    @Operation(summary = "获取所有用户", description = "获取系统中所有用户的信息")
    public String getUsers() {
        return "All users";
    }
}

3.3 @ApiParam注解

@ApiParam 注解用于标记方法参数，提供参数的详细信息：

import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/user")
    public String getUser(@Parameter(name = "id", description = "用户ID", required = true) @RequestParam Long id) {
        return "User with id: " + id;
    }
}

四、分组管理API文档

4.1 配置多个Docket

可以通过配置多个 Docket 实例来实现 API 文档的分组管理：

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

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.OAS_30)
               .groupName("用户管理")
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.user"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
    }

    @Bean
    public Docket orderApi() {
        return new Docket(DocumentationType.OAS_30)
               .groupName("订单管理")
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.order"))
               .paths(PathSelectors.any())
               .build()
               .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot + Swagger3 API文档")
               .description("API文档详细描述")
               .version("1.0.0")
               .build();
    }
}

4.2 访问分组文档

在 Swagger UI 界面中，可以通过下拉菜单选择不同的分组查看相应的 API 文档。

五、隐藏不必要的API

5.1 使用PathSelectors

可以通过 PathSelectors 来过滤不需要显示的 API：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.ant("/api/**"))
               .build();
    }
}

上述代码只显示以 /api/ 开头的 API。

5.2 使用@ApiIgnore注解

在控制器类或方法上添加 @ApiIgnore 注解，可以忽略该类或方法的 API 文档：

import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/users")
    public String getUsers() {
        return "All users";
    }

    @GetMapping("/internal")
    @Hidden
    public String internalApi() {
        return "Internal API";
    }
}

六、自定义响应消息

6.1 使用@ApiResponse注解

@ApiResponse 注解用于定义 API 方法的响应消息：

import io.swagger.v3.oas.annotations.Operation;
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;

@RestController
public class UserController {

    @GetMapping("/user")
    @Operation(summary = "获取用户信息")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "成功获取用户信息"),
            @ApiResponse(responseCode = "404", description = "用户不存在")
    })
    public String getUser() {
        return "User info";
    }
}

6.2 全局响应消息配置

可以通过实现 WebMvcConfigurer 接口来配置全局的响应消息：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    // 配置全局响应消息
}

七、处理复杂数据类型

7.1 自定义模型转换器

当遇到复杂数据类型时，可以自定义模型转换器来处理：

import com.fasterxml.jackson.databind.module.SimpleModule;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spring.web.json.JacksonModuleRegistrar;

@Configuration
public class SwaggerModelConfig {

    @Bean
    public JacksonModuleRegistrar swaggerJacksonModuleRegistrar() {
        return objectMapper -> {
            SimpleModule module = new SimpleModule();
            // 注册自定义序列化器和反序列化器
            objectMapper.registerModule(module);
        };
    }
}

7.2 使用@Schema注解

@Schema 注解用于描述模型类的属性：

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户信息")
public class User {

    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户名", example = "John Doe")
    private String name;

    //  getter 和 setter 方法
}

八、集成Swagger3到生产环境

8.1 条件配置

可以通过条件配置来控制 Swagger3 在生产环境中是否启用：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    @Profile("!prod")
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build();
    }
}

上述代码表示只有在非生产环境中才启用 Swagger3。

8.2 安全访问

在生产环境中，可以通过配置安全访问来限制 Swagger UI 的访问：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
               .authorizeRequests()
               .antMatchers("/swagger-ui/**", "/v3/api-docs/**").authenticated()
               .anyRequest().permitAll()
               .and()
               .httpBasic();
        return http.build();
    }
}

九、自动化测试与Swagger3

9.1 生成测试用例

可以根据 Swagger3 生成的 API 文档自动生成测试用例，例如使用 Postman 等工具导入 Swagger 文档并生成测试用例。

9.2 持续集成

将 Swagger3 集成到持续集成流程中，每次代码更新后自动生成 API 文档并进行测试，确保 API 的稳定性。

十、性能优化与缓存

10.1 缓存 Swagger 文档

可以使用缓存技术来缓存 Swagger 生成的 API 文档，减少每次请求时的生成时间：

import org.springframework.cache.annotation.Cacheable;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build();
    }

    @Cacheable("swagger-docs")
    public Object getSwaggerDocs() {
        // 获取 Swagger 文档
        return null;
    }
}

10.2 优化 Swagger 扫描

减少不必要的包扫描范围，只扫描需要生成 API 文档的控制器类，提高性能。

SpringBoot集成Swagger3
czxboys的博客
05-31 971
SpringBoot集成Swagger3 文章目录SpringBoot集成Swagger31、Maven项目引入swagger依赖2、接口相关配置（WebMvcConfig类）3、添加静态资源映射（WebMvcConfig类）4、不拦截接口路径（WebMvcConfig类）5、Swagger常用注解 swagger官网：API Documentation & Design Tools for Teams | Swagger 1、Maven项目引入swagger依赖 <depen
SpringBoot整合Swagger生成接口文档
Smily-王婷婷
07-25 836
引入  现在的项目大多数都是前后端分离，所以对于后端开发，我们需要一个接口工具帮我们进行接口的整理、也方便我们测试。推荐postMan和Swaager形式，然后postMan需要自己手写接口，然后参数需要手动粘贴，但是相比于它，Sagger就相对方便很多了，他会根据后台的代码，然后自动生成接口以及参数名。 应用 在pom.xml中引入相应的依赖jar包 配置Swagger2配置文件` @C...
Spring boot 使用 Swagger3 生成API接口文档
BBX__XB的博客
07-20 1240
Springboot使用Swagger3生成API接口文档（入门详细教程）
Java实战：Spring Boot集成Swagger3
oandy0的博客
02-23 6941
本文将详细介绍如何在Spring Boot应用程序中集成Swagger3，以构建现代化的RESTful API文档
【springboot】springboot使用swagger3
编程笔记
12-09 288
springboot使用swagger3 1、pom.xml添加依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependen
springboot 集成 Swagger3（速通）
m0_54355172的博客
05-25 5209
一杯奶茶的时间学会使用springboot集成swagger3
Spring Boot：Swagger生成接口文档并调试接口
安晴晚风的博客
08-01 2396
使用Swagger只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。
Springboot集成Swagger实现接口文档自动生成
悠杨的专栏
11-25 1513
在实时接口文档的生成方案中，Swagger是最具影响力的一个。本文介绍了在Springboot项目中如何集成Swagger2和3，来实现接口文档的自动生成和更新的方法。
SpringBoot——SpringBoot生成接口文档
庄小焱
03-30 7554
SpringBoot开发Restful接口，有什么API规范吗？如何快速生成API文档呢？Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。本文主要介绍OpenAPI规范，以及Swagger技术栈基于OpenAPI规范的集成方案。
Springboot集成Swagger自动生成接口文档
weixin_45116528的博客
11-19 586
Springboot集成Swagger自动生成接口文档为什么使用Swagger来自动生成接口文档1.项目集成Swagger1.1 Maven集成Swagger1.2 Gradle集成Swagger2.开始配置Swagger3.处理入参的实体类User4.处理Controller5.修改Springboot启动类6.访问通过注解自动生成的SwaggerUi7.后续更新第二种界面 为什么使用Swagger来自动生成接口文档 Swagger是一个完整的框架，项目上用于自动化生成对应的接口文档并且可以在可视化工具上
SpringBoot:Springboot+swagger 多数据源
04-29
在SpringBoot项目中集成Swagger，可以帮助我们进行API的自动化测试和接口文档的生成，极大地提高了开发效率和协作的便利性。 首先，让我们详细探讨一下SpringBoot集成多数据源。在企业级应用中，经常会出现需要连接...
源码：整合springboot+mybatis+swagger+jwt+security实现api文档以及token验证
最新发布
11-18
接着，Swagger是一个可以自动化生成API文档的工具。它能够从代码注释和元数据中提取信息，并生成清晰且易于阅读的API文档。Swagger的集成可以让开发者更加方便地管理API接口，同时也能提供给前端开发者清晰的接口...
springboot+swagger的一个小Demo
10-23
SpringBoot和Swagger2是两个在Java开发领域广泛应用的开源项目，它们在构建高效、文档化的Web服务方面发挥了重要作用。SpringBoot简化了Spring框架的配置，提供了快速开发Java应用的环境，而Swagger2则是一个用于...
SpringBoot+Swagger-ui：自动化API文档生成与实战
本文档主要介绍了如何在SpringBoot项目中集成Swagger-ui，实现API文档的自动生成。随着前后端分离的趋势，API文档的管理变得尤为重要，而Swagger是一个广泛使用的工具，用于生成RESTful风格接口的文档，并提供在线...
Spring Boot 集成 Swagger，生成接口文档就这么简单！
Java技术栈，分享最主流的Java技术
03-19 1242
之前的文章介绍了《推荐一款接口 API 设计神器！》，今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成，简直不能太简单。 你所需具备的基础 告诉你，Spring Boot 真是个牛逼货！ Spring Boot 核心配置文件详解 Spring Boot 开启的 2 种方式 Spring Boot 自动配置原理、实战 Spring Boot 2.x 启动全过程源码分析 更多...
【springboot】使用swagger生成接口文档
BlackPudding_的博客
09-04 926
这里我老是添加不上这个依赖，搜索了下发现阿里云公共仓库中没有这个依赖，所以一直找不到。于是修改了下maven的setting文件，添加了阿里云的中心仓库的镜像。
SpringBoot3使用Swagger3
Q95470的博客
06-17 4050
Swagger是一个用于设计、构建、文档化和使用RESTful Web服务的开源工具。Swagger3是Swagger的最新版本，它提供了许多新功能和改进。Swagger在SpringBoot3中的引入方法发生了改变,网上大部分还是SpringBoot2的版本。访问http://localhost:9090/swagger-ui/index.html#/其中的9090 改成你项目后端使用的端口，注意不能省略后面的index.html。版本也可以使用新版，Springdoc-OpenAPI。
评论 1
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

fanxbl957

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值