API文档自动化：SpringBoot + Swagger3接口文档生成的10个技巧
🌟博主介绍：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.springfoxgroupId>
<artifactId>springfox-boot-starterartifactId>
<version>3.0.0version>
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 文档的控制器类，提高性能。
