SpringBoot整合Swagger3：从入门到精通（亲测可用）

最新推荐文章于 2025-05-31 22:32:21 发布
最新推荐文章于 2025-05-31 22:32:21 发布
阅读量971 收藏 10
点赞数 27
分类专栏： # 核心功能 文章标签： spring boot java swagger3
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_27756951/article/details/148269301
版权

文章目录

一、Swagger简介与核心概念

1.1 什么是Swagger？

Swagger是一套围绕OpenAPI规范构建的开源工具，它可以帮助我们设计、构建、记录和使用RESTful API。简单来说，Swagger就像是你API的"说明书"和"测试工具"合二为一。

日常生活化比喻：想象你去一家餐厅，菜单就是API文档。传统方式是你需要手动写一份纸质菜单（Word文档），而Swagger则是一个电子菜单屏，不仅能展示菜品（API接口），还能直接下单测试（调用接口），并且当菜品更新时菜单会自动同步（与代码同步更新）。

1.2 Swagger核心组件

组件名称功能描述类比日常生活
Swagger UI可视化API文档界面餐厅的电子点菜屏
Swagger EditorAPI设计编辑器菜单设计师的工作台
Swagger Codegen代码生成工具根据设计图自动做菜的机器人厨师
Swagger Hub云端API协作平台连锁餐厅的中央厨房管理系统

1.3 Swagger2 vs Swagger3

特性Swagger2Swagger3 (OpenAPI 3.0)
规范基础Swagger规范OpenAPI 3.0规范
依赖springfox-swagger2springdoc-openapi-ui
注解包io.swagger.annotationsio.swagger.v3.oas.annotations
安全性有限支持更强大的安全方案支持
性能较低更高
社区支持维护中活跃开发
组件复用有限更好的组件复用支持
文件上传简单支持多部分请求更好支持

为什么选择Swagger3：

  • 遵循最新的OpenAPI 3.0规范
  • 更好的性能
  • 更活跃的社区支持
  • 更丰富的功能特性

二、SpringBoot集成Swagger3

2.1 基础环境搭建

2.1.1 添加Maven依赖
<!-- SpringDoc OpenAPI (Swagger3) -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

<!-- 如果使用WebFlux -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webflux-ui</artifactId>
    <version>1.6.14</version>
</dependency>
2.1.2 基础配置类
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("电商平台API文档")
                        .version("1.0")
                        .description("这是一个电商平台的后端API文档")
                        .termsOfService("http://swagger.io/terms/")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }
}

配置项解析：

  • title: API文档标题，相当于书的封面标题
  • version: API版本号，像书的版次
  • description: API描述，相当于书的简介
  • termsOfService: 服务条款URL
  • license: 许可证信息

2.2 访问Swagger UI

启动应用后，可以通过以下URL访问：

  • Swagger UI界面: http://localhost:8080/swagger-ui.html
  • OpenAPI JSON描述: http://localhost:8080/v3/api-docs

界面解读：

  1. 顶部：API文档标题和版本
  2. 左侧：API分组列表（控制器列表）
  3. 右侧：API详细信息区域
  4. 顶部搜索框：可以快速搜索API
  5. "Try it out"按钮：可以直接测试API

三、Swagger3注解详解

3.1 常用注解概览

注解作用范围功能描述类比日常生活
@TagController类对API进行分组书的章节标题
@Operation方法描述API操作章节中的小节标题
@Parameter参数描述单个参数菜谱中的食材清单
@Schema模型属性描述模型属性产品说明书中的规格参数
@ApiResponse方法描述响应状态码家电的故障代码说明
@Hidden类/方法/字段隐藏API或属性商业秘密，不对外公开

3.2 控制器层注解

3.2.1 @Tag - 控制器分组
@RestController
@RequestMapping("/api/products")
@Tag(name = "产品管理", description = "产品相关的API，包括CRUD操作")
public class ProductController {
    // 控制器方法...
}

参数说明：

  • name: 必填，分组名称
  • description: 可选，分组描述
3.2.2 @Operation - 方法描述
@GetMapping("/{id}")
@Operation(
    summary = "获取产品详情",
    description = "根据ID获取单个产品的详细信息",
    tags = { "产品管理" },
    parameters = {
        @Parameter(name = "id", description = "产品ID", required = true)
    }
)
public ResponseEntity<Product> getProductById(@PathVariable Long id) {
    // 方法实现...
}

参数说明：

  • summary: 简短描述，显示在方法列表
  • description: 详细描述
  • tags: 所属标签（与@Tag的name对应）
  • parameters: 参数描述
3.2.3 @Parameter - 参数描述
@GetMapping("/search")
@Operation(summary = "搜索产品")
public List<Product> searchProducts(
    @Parameter(description = "产品名称关键字", example = "手机") 
    @RequestParam String keyword,
    
    @Parameter(description = "最低价格", example = "1000") 
    @RequestParam(required = false) Double minPrice,
    
    @Parameter(description = "最高价格", example = "5000") 
    @RequestParam(required = false) Double maxPrice) {
    // 方法实现...
}

参数说明：

  • description: 参数描述
  • required: 是否必填
  • example: 示例值
  • hidden: 是否隐藏

3.3 模型层注解

3.3.1 @Schema - 模型属性描述
public class Product {
    
    @Schema(description = "产品ID", example = "1")
    private Long id;
    
    @Schema(description = "产品名称", example = "智能手机", required = true)
    private String name;
    
    @Schema(description = "产品价格", example = "2999.99")
    private BigDecimal price;
    
    @Schema(description = "库存数量", example = "100")
    private Integer stock;
    
    @Schema(description = "上架状态", example = "true")
    private Boolean onSale;
    
    @Schema(description = "创建时间", example = "2023-01-01 10:00:00")
    private LocalDateTime createTime;
    
    // getters and setters...
}

参数说明：

  • description: 属性描述
  • example: 示例值
  • required: 是否必填
  • hidden: 是否隐藏
  • allowableValues: 允许的值范围
3.3.2 枚举类型描述
public enum OrderStatus {
    @Schema(description = "待支付")
    PENDING,
    
    @Schema(description = "已支付")
    PAID,
    
    @Schema(description = "已发货")
    SHIPPED,
    
    @Schema(description = "已完成")
    COMPLETED,
    
    @Schema(description = "已取消")
    CANCELLED
}

3.4 响应注解

3.4.1 @ApiResponse - 响应状态描述
@PostMapping
@Operation(summary = "创建新产品")
@ApiResponses({
    @ApiResponse(responseCode = "201", description = "产品创建成功"),
    @ApiResponse(responseCode = "400", description = "无效的输入参数"),
    @ApiResponse(responseCode = "500", description = "服务器内部错误")
})
public ResponseEntity<Product> createProduct(@RequestBody Product product) {
    // 方法实现...
    return ResponseEntity.status(HttpStatus.CREATED).body(savedProduct);
}

参数说明：

  • responseCode: HTTP状态码
  • description: 状态描述
  • content: 响应内容描述（复杂响应时使用）
3.4.2 响应内容描述
@GetMapping("/{id}")
@Operation(summary = "获取产品详情")
@ApiResponse(responseCode = "200", description = "成功获取产品详情",
    content = @Content(mediaType = "application/json", 
        schema = @Schema(implementation = Product.class)))
public Product getProductById(@PathVariable Long id) {
    // 方法实现...
}

四、Swagger3高级配置

4.1 全局参数配置

4.1.1 添加全局请求头
/**
 * 该方法创建一个名为 customOpenAPI 的 Spring Bean，用于生成自定义的 OpenAPI 规范对象。
 * OpenAPI 规范可以描述 RESTful API 的结构和使用方式，方便开发者生成 API 文档、测试代码等。
 *
 * @return 自定义配置的 OpenAPI 对象
 */
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            // 设置 OpenAPI 文档的基本信息
            .info(new Info()
                    // 设置 API 文档的标题
                    .title("API文档")
                    // 设置 API 文档的版本号
                    .version("1.0"))
            // 添加安全需求，表明此 API 需要进行安全认证
            .addSecurityItem(new SecurityRequirement()
                    // 添加一个名为 "Authorization" 的安全方案列表，意味着所有 API 操作都需要使用该安全方案进行认证
                    .addList("Authorization"))
            // 设置 OpenAPI 文档的组件，组件可包含安全方案、响应模式等
            .components(new Components()
                    // 添加一个名为 "Authorization" 的安全方案
                    .addSecuritySchemes("Authorization",
                            new SecurityScheme()
                                    // 设置安全方案的类型为 HTTP 认证
                                    .type(SecurityScheme.Type.HTTP)
                                    // 设置 HTTP 认证的方案为 bearer token 认证
                                    .scheme("bearer")
                                    // 指定 bearer token 的格式为 JWT（JSON Web Token）
                                    .bearerFormat("JWT")));
}
4.1.2 全局参数
/**
 * 此方法定义了一个名为 customOpenAPI 的 Spring Bean，用于创建自定义的 OpenAPI 规范对象。
 * OpenAPI 规范可用于详细描述 RESTful API 的结构、请求参数、响应格式等信息，方便开发者生成 API 文档和进行接口测试。
 *
 * @return 自定义配置的 OpenAPI 对象
 */
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            // 设置 OpenAPI 文档的基本信息
            .info(new Info()
                    // 为 API 文档设置标题
                    .title("API文档")
                    // 指定 API 文档的版本号
                    .version("1.0"))
            // 配置 OpenAPI 文档的组件，这里主要用于添加参数等信息
            .components(new Components()
                    // 添加一个名为 "pageNumber" 的参数
                    .addParameters("pageNumber",
                            new Parameter()
                                    // 指定该参数位于查询字符串中
                                    .in("query")
                                    // 定义参数的名称为 "pageNumber"
                                    .name("pageNumber")
                                    // 对参数进行描述，表明该参数代表页码
                                    .description("页码")
                                    // 设置该参数为非必需参数
                                    .required(false)
                                    // 定义参数的模式，这里指定参数类型为整数，并设置默认值为 1
                                    .schema(new Schema().type("integer").defaultValue(1)))
                    // 添加一个名为 "pageSize" 的参数
                    .addParameters("pageSize",
                            new Parameter()
                                    // 指定该参数位于查询字符串中
                                    .in("query")
                                    // 定义参数的名称为 "pageSize"
                                    .name("pageSize")
                                    // 对参数进行描述，表明该参数代表每页显示的数量
                                    .description("每页数量")
                                    // 设置该参数为非必需参数
                                    .required(false)
                                    // 定义参数的模式，这里指定参数类型为整数，并设置默认值为 10
                                    .schema(new Schema().type("integer").defaultValue(10))));
}

4.2 分组配置

@Bean
@Primary
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/api/public/**")
            .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin")
            .pathsToMatch("/api/admin/**")
            .addOpenApiMethodFilter(method -> method.isAnnotationPresent(PreAuthorize.class))
            .build();
}

访问不同分组：

  • public组: http://localhost:8080/swagger-ui.html?group=public
  • admin组: http://localhost:8080/swagger-ui.html?group=admin

4.3 安全配置

4.3.1 JWT认证配置
/**
 * 定义一个名为 customOpenAPI 的 Spring Bean，用于创建自定义的 OpenAPI 规范对象。
 * OpenAPI 规范是用于描述 RESTful API 的标准，可用于生成 API 文档、客户端代码等。
 *
 * @return 自定义的 OpenAPI 规范对象
 */
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            // 设置 OpenAPI 文档的基本信息
            .info(new Info()
                    // 设置 API 文档的标题
                    .title("API文档")
                    // 设置 API 文档的版本号
                    .version("1.0"))
            // 添加安全需求，表明该 API 需要使用 JWT 进行身份验证
            .addSecurityItem(new SecurityRequirement()
                    // 添加一个名为 "JWT" 的安全方案列表
                    .addList("JWT"))
            // 设置 OpenAPI 文档的组件，包括安全方案等
            .components(new Components()
                    // 添加一个名为 "JWT" 的安全方案
                    .addSecuritySchemes("JWT",
                            new SecurityScheme()
                                    // 设置安全方案的类型为 HTTP
                                    .type(SecurityScheme.Type.HTTP)
                                    // 设置 HTTP 认证方案为 bearer token
                                    .scheme("bearer")
                                    // 指定 bearer token 的格式为 JWT
                                    .bearerFormat("JWT")
                                    // 指定 token 所在的位置为请求头
                                    .in(SecurityScheme.In.HEADER)
                                    // 指定请求头中携带 token 的字段名为 "Authorization"
                                    .name("Authorization")));
}
4.3.2 OAuth2配置
/**
 * 此方法会创建一个 Spring Bean，用于生成自定义的 OpenAPI 对象。
 * OpenAPI 规范可用于描述 RESTful API，有助于生成 API 文档、客户端代码等。
 *
 * @return 自定义的 OpenAPI 规范对象
 */
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            // 配置 OpenAPI 文档的基本信息
            .info(new Info()
                    // 设置 API 文档的标题
                    .title("API文档")
                    // 设置 API 文档的版本号
                    .version("1.0"))
            // 配置 OpenAPI 文档的组件，像安全方案等内容都可在此配置
            .components(new Components()
                    // 添加一个名为 "oauth2" 的安全方案
                    .addSecuritySchemes("oauth2",
                            new SecurityScheme()
                                    // 设置安全方案的类型为 OAuth 2.0
                                    .type(SecurityScheme.Type.OAUTH2)
                                    // 配置 OAuth 2.0 的授权流程
                                    .flows(new OAuthFlows()
                                            // 采用隐式授权流程
                                            .implicit(new OAuthFlow()
                                                    // 设置授权请求的 URL，客户端会重定向到该 URL 以获取授权码
                                                    .authorizationUrl("https://example.com/oauth2/authorize")
                                                    // 配置授权范围
                                                    .scopes(new Scopes()
                                                            // 添加一个名为 "read" 的授权范围，描述为 "读取权限"
                                                            .addString("read", "读取权限")
                                                            // 添加一个名为 "write" 的授权范围，描述为 "写入权限"
                                                            .addString("write", "写入权限"))))));
}
}

4.4 自定义UI配置

# application.properties
springdoc.swagger-ui.path=/api-docs
springdoc.swagger-ui.tagsSorter=alpha
springdoc.swagger-ui.operationsSorter=alpha
springdoc.swagger-ui.docExpansion=none
springdoc.swagger-ui.filter=true
springdoc.swagger-ui.persistAuthorization=true
springdoc.swagger-ui.display-request-duration=true

常用配置项：

  • path: Swagger UI路径
  • tagsSorter: 标签排序方式(alpha/method)
  • operationsSorter: 操作排序方式(alpha/method)
  • docExpansion: 文档展开方式(none/list/full)
  • filter: 是否显示搜索框
  • persistAuthorization: 是否保持授权信息
  • display-request-duration: 是否显示请求持续时间

五、实战案例：电商系统API文档

5.1 产品管理模块

@RestController
@RequestMapping("/api/products")
@Tag(name = "产品管理", description = "产品相关的CRUD操作")
public class ProductController {

    @Autowired
    private ProductService productService;

    @GetMapping
    @Operation(summary = "获取产品列表", description = "分页获取所有产品")
    @Parameters({
        @Parameter(name = "page", description = "页码", example = "1"),
        @Parameter(name = "size", description = "每页数量", example = "10")
    })
    public Page<Product> getProducts(
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "10") int size) {
        return productService.getProducts(page, size);
    }

    @GetMapping("/{id}")
    @Operation(summary = "获取产品详情", description = "根据ID获取单个产品")
    @ApiResponse(responseCode = "200", description = "成功获取产品")
    @ApiResponse(responseCode = "404", description = "产品不存在")
    public Product getProductById(
            @Parameter(description = "产品ID", required = true, example = "1")
            @PathVariable Long id) {
        return productService.getProductById(id);
    }

    @PostMapping
    @Operation(summary = "创建产品", description = "创建新产品")
    @ApiResponse(responseCode = "201", description = "产品创建成功")
    @ApiResponse(responseCode = "400", description = "无效的输入")
    public ResponseEntity<Product> createProduct(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                description = "产品信息", 
                required = true,
                content = @Content(
                    schema = @Schema(implementation = Product.class),
                    examples = @ExampleObject(
                        value = "{\"name\": \"智能手机\", \"price\": 2999.99, \"stock\": 100}"
                    )
                )
            )
            @Valid @RequestBody Product product) {
        Product savedProduct = productService.createProduct(product);
        return ResponseEntity.status(HttpStatus.CREATED).body(savedProduct);
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新产品", description = "更新现有产品信息")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "产品更新成功"),
        @ApiResponse(responseCode = "400", description = "无效的输入"),
        @ApiResponse(responseCode = "404", description = "产品不存在")
    })
    public Product updateProduct(
            @Parameter(description = "产品ID", required = true, example = "1")
            @PathVariable Long id,
            @Valid @RequestBody Product product) {
        return productService.updateProduct(id, product);
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "删除产品", description = "删除指定产品")
    @ApiResponse(responseCode = "204", description = "产品删除成功")
    @ApiResponse(responseCode = "404", description = "产品不存在")
    public ResponseEntity<Void> deleteProduct(
            @Parameter(description = "产品ID", required = true, example = "1")
            @PathVariable Long id) {
        productService.deleteProduct(id);
        return ResponseEntity.noContent().build();
    }
}

5.2 订单管理模块

@RestController
@RequestMapping("/api/orders")
@Tag(name = "订单管理", description = "订单相关的操作")
public class OrderController {

    @Autowired
    private OrderService orderService;

    @PostMapping
    @Operation(summary = "创建订单", description = "根据购物车创建新订单")
    @ApiResponse(responseCode = "201", description = "订单创建成功")
    @ApiResponse(responseCode = "400", description = "无效的输入")
    public ResponseEntity<Order> createOrder(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                description = "订单信息",
                required = true,
                content = @Content(
                    schema = @Schema(implementation = OrderRequest.class),
                    examples = @ExampleObject(
                        value = "{\"userId\": 1, \"items\": [{\"productId\": 1, \"quantity\": 2}]}"
                    )
                )
            )
            @Valid @RequestBody OrderRequest orderRequest) {
        Order order = orderService.createOrder(orderRequest);
        return ResponseEntity.status(HttpStatus.CREATED).body(order);
    }

    @GetMapping("/{orderId}")
    @Operation(summary = "获取订单详情", description = "根据订单ID获取订单详情")
    @ApiResponse(responseCode = "200", description = "成功获取订单")
    @ApiResponse(responseCode = "404", description = "订单不存在")
    public Order getOrder(
            @Parameter(description = "订单ID", required = true, example = "ORD-123456")
            @PathVariable String orderId) {
        return orderService.getOrder(orderId);
    }

    @GetMapping("/user/{userId}")
    @Operation(summary = "获取用户订单", description = "获取指定用户的所有订单")
    @Parameters({
        @Parameter(name = "page", description = "页码", example = "1"),
        @Parameter(name = "size", description = "每页数量", example = "10")
    })
    public Page<Order> getUserOrders(
            @Parameter(description = "用户ID", required = true, example = "1")
            @PathVariable Long userId,
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "10") int size) {
        return orderService.getUserOrders(userId, page, size);
    }

    @PatchMapping("/{orderId}/status")
    @Operation(summary = "更新订单状态", description = "更新订单状态")
    @ApiResponse(responseCode = "200", description = "状态更新成功")
    @ApiResponse(responseCode = "400", description = "无效的状态")
    @ApiResponse(responseCode = "404", description = "订单不存在")
    public Order updateOrderStatus(
            @Parameter(description = "订单ID", required = true, example = "ORD-123456")
            @PathVariable String orderId,
            @Parameter(description = "新状态", required = true, 
                       schema = @Schema(implementation = OrderStatus.class))
            @RequestParam OrderStatus status) {
        return orderService.updateOrderStatus(orderId, status);
    }
}

六、Swagger3最佳实践

6.1 文档规范建议

  1. 命名一致性：

    • 使用一致的命名规范（如全部小写，单词用连字符连接）
    • 保持路径结构一致（如/api/{resource}）

  2. 版本控制：

    • 在路径中包含版本号（如/api/v1/products）
    • 使用@Tag标注API版本

  3. 响应标准化：

    • 使用统一响应格式
    • 包含标准错误码和消息

6.2 性能优化

  1. 按需加载：

    • 使用分组功能只加载必要的API
    • 生产环境可以禁用Swagger UI

  2. 缓存配置：

    springdoc.cache.disabled=false

  3. 生产环境配置：

    # 生产环境禁用Swagger UI
springdoc.swagger-ui.enabled=false
# 但保留API文档端点（可选）
springdoc.api-docs.enabled=true

6.3 安全性建议

  1. 访问控制：

    @Profile({"dev", "test"})  // 只在开发和测试环境启用
@Configuration
public class SwaggerConfig {
    // 配置内容...
}

  2. 敏感信息保护：

    • 使用@Hidden隐藏敏感API
    • 避免在文档中暴露敏感字段

  3. HTTPS：

    • 确保Swagger UI通过HTTPS访问
    • 配置正确的服务器URL：
      @Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .servers(List.of(new Server().url("https://api.example.com")));
}

七、常见问题与解决方案

7.1 常见问题排查表

问题现象可能原因解决方案
404访问不到Swagger UI路径配置错误/依赖缺失检查springdoc.swagger-ui.path配置
模型显示不正确未使用@Schema注解为模型添加@Schema注解
参数描述不显示未使用@Parameter为参数添加@Parameter注解
分组不生效分组配置错误检查GroupedOpenApi配置
授权无效安全配置不正确检查SecurityScheme配置

7.2 与Spring Security集成

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/swagger-ui/**").permitAll()
                .antMatchers("/v3/api-docs/**").permitAll()
                .anyRequest().authenticated()
            .and()
            .formLogin().disable()
            .csrf().disable();
    }
}

7.3 自定义文档处理器

@Bean
public OpenApiCustomiser openApiCustomiser() {
    return openApi -> {
        // 添加服务器信息
        openApi.addServersItem(new Server().url("http://localhost:8080").description("本地环境"));
        openApi.addServersItem(new Server().url("https://dev.example.com").description("开发环境"));
        
        // 添加扩展信息
        openApi.addExtension("x-api-version", "1.0.0");
        
        // 修改默认响应
        openApi.getPaths().values().forEach(pathItem -> {
            pathItem.readOperations().forEach(operation -> {
                operation.getResponses().addApiResponse("500", 
                    new ApiResponse().description("服务器内部错误"));
            });
        });
    };
}

八、Swagger3扩展与进阶

8.1 多语言支持

@Bean
public OpenAPI customOpenAPI(MessageSource messageSource) {
    return new OpenAPI()
            .info(new Info()
                    .title(messageSource.getMessage("swagger.title", null, LocaleContextHolder.getLocale()))
                    .description(messageSource.getMessage("swagger.description", null, LocaleContextHolder.getLocale()))
                    .version("1.0"));
}

8.2 动态文档生成

@RestController
@RequestMapping("/api/dynamic")
@Tag(name = "动态API", description = "动态生成的API")
public class DynamicApiController {

    @GetMapping("/{resource}")
    @Operation(summary = "获取动态资源")
    @Parameter(name = "resource", description = "资源类型", example = "users")
    public ResponseEntity<?> getDynamicResource(
            @PathVariable String resource,
            @RequestParam Map<String, String> allParams) {
        // 根据resource和参数动态处理
        return ResponseEntity.ok().build();
    }

    @Bean
    public OpenApiCustomiser dynamicApiCustomiser() {
        return openApi -> {
            PathItem pathItem = new PathItem()
                    .get(new Operation()
                            .addTagsItem("动态API")
                            .summary("动态资源操作")
                            .addParametersItem(new Parameter()
                                    .name("resource")
                                    .in("path")
                                    .description("资源类型")
                                    .required(true)
                                    .schema(new StringSchema())))
                    .post(new Operation()
                            .addTagsItem("动态API")
                            .summary("创建动态资源"));
            
            openApi.path("/api/dynamic/{resource}", pathItem);
        };
    }
}

8.3 自定义UI主题

  1. 添加自定义CSS文件到resources/static/swagger-ui/目录
  2. 配置自定义CSS路径：
    springdoc.swagger-ui.config-url=/swagger-ui/swagger-config.yml
springdoc.swagger-ui.css-url=/swagger-ui/custom.css

示例custom.css：

.swagger-ui .topbar {
    background-color: #2c3e50;
}

.swagger-ui .info .title {
    color: #27ae60;
}

.opblock-tag {
    background-color: #f8f9fa;
    border-left: 4px solid #3498db;
}

九、总结与资源推荐

9.1 关键点回顾

  1. Swagger3优势：

    • 遵循OpenAPI 3.0规范
    • 更好的性能和扩展性
    • 更丰富的注解支持

  2. 核心注解：

    • @Tag - API分组
    • @Operation - 方法描述
    • @Parameter - 参数描述
    • @Schema - 模型描述

  3. 最佳实践：

    • 合理分组API
    • 生产环境安全控制
    • 统一的文档规范

关注不关注，你自己决定（但正确的决定只有一个）。

喜欢的点个关注，想了解更多的可以关注微信公众号 “Eric的技术杂货库” ，提供更多的干货以及资料下载保存！

Spring Boot进阶(26)：从小白到高手，掌握Mybatis中resultType和resultMap的秘密！
**My Coding Family**
06-01 2431
springboot之resultType及resultMap的正确打开方式,入门级教学，确定不看一眼吗？
Spring Boot进阶(57)：Spring中@Autowired不适用的场景，不要掉进坑里！
**My Coding Family**
07-19 1970
Spring中什么时候不要用@Autowired注入？你若不会我可以教你。
SpringBoot整合Swagger2：从入门到精通（亲测可用）
Clf丶忆笙
05-30 1644
Swagger2是一款基于OpenAPI规范的开源工具集，用于RESTful API的设计、文档化和测试。本文介绍了Swagger2的核心价值、SpringBoot集成步骤和注解使用。通过对比传统文档方式，Swagger2具有实时同步、可视化测试和交互性等优势。集成过程包含依赖配置、SwaggerConfig类编写和UI访问。文章详细解析了控制器层注解如@Api、@ApiOperation的实战应用，以及参数描述注解的使用技巧，帮助开发者快速构建规范的API文档系统。
SpringBoot从入门到精通教程
Think Different
08-25 14万+
对于SpringBoot，很多人咨询了我的研究学习资料来源，除官方文档外，特例完整整理一下自己的平时参考学习其他资料，以及分享实战项目源码和代码资源，供大家参考学习 主要教程 一、我的SpringBoot系列教程（2020.3更新） 我的SpringBoot系列进阶教程（Github仓库源码地址） 基于springboot 2.0.6.RELEASE版本的代码演示集合： SpringBo...
Springboot入门到精通（超详细文档）
热门推荐
cuiqwei的博客
06-24 36万+
1. Spring Boot是什么 我们知道，从 2002 年开始，Spring 一直在飞速的发展，如今已经成为了在Java EE（Java Enterprise Edition）开发中真正意义上的标准，但是随着技术的发展，Java EE使用 Spring 逐渐变得笨重起来，大量的 XML 文件存在于项目之中。繁琐的配置，整合第三方框架的配置问题，导致了开发和部署效率的降低。 2012 年 10 月，Mike Youngstrom 在 Spring jira 中创建了一个功能请求，要求在 Spring
牛逼！Java 从入门到精通，超全汇总版
程序员cxuan的个人主页
05-06 11万+
文章目录Java 基础Head First JavaJava 核心技术卷一Java 编程思想设计模式Head First 设计模式图解设计模式设计模式重学 Java 设计模式Java 进阶Java 并发编程实战Java 并发编程艺术Java 并发编程之美图解Java多线程设计模式JVM深入理解 Java 虚拟机Java 虚拟机规范HotSpot 实战自己动手写 Java 虚拟机MySQLMySQL 基础教程SQL 基础教程深入浅出 MySQLMySQL 必知必会SQL 必知必会高性能 MySQLMySQL
逐步学习 Swagger enum：从入门到精通
LiamHong_的博客
11-10 691
在 Swagger 规范中，使用enum关键字定义枚举值。例如，我们可以在参数定义中使用enumin: queryenum:- active- inactive在这个示例中，status参数的可能取值只能是active或inactive。
Spring Boot入门到精通（超详细）
qq_41627024的博客
06-06 6546
本文主要讲了Springboot从基础到高阶涉及到的相关技术，让读者能够快速入门，深入了解Springboot框架，并能够熟练的使用springboot，快速提升个人技能。
【SpringCloud】从入门到精通（下）
shenqibaobao的博客
04-09 793
自定义GatewayFilter不是直接实现GatewayFilter，而是实现AbstractGatewayFilterFactory。@Component@Override@Override// 获取请求// 编写过滤器逻辑System.out.println("过滤器执行了");// 放行注意：该类的名称一定要以GatewayFilterFactory为后缀！
从入门到精通 SpringSecurity & Auth2.0
安静的软件工程师
08-16 1036
从入门到精通 SpringSecurity & Auth2.0
Springboot 入门到精通（超详细文档）
u011997561的博客
02-07 5605
springboot
Spring Boot 中 @RequestParam 和 @RequestPart 的区别详解（含实际项目案例）
Mylvzi的博客
05-30 915
比较点适用请求类型适用参数类型简单类型（字符串、文件、数字）复杂类型（JSON 对象、多个文件、嵌套结构）JSON 自动转换❌ 不支持✅ 支持（通过 HttpMessageConverter）常见使用场景普通表单提交、单文件上传JSON + 文件上传、富表单场景理解和的使用场景，能够帮助我们在设计接口时做出更合适的技术选择，也能避免参数绑定错误、JSON 转换失败等常见问题。✍️ 作者：Lvzi📅 时间：2025年。
Spring Boot项目中实现单点登录(SSO)完整指南
wa_ka_ka的博客
05-28 1225
单点登录(Single Sign-On, SSO)是一种身份验证机制，允许用户使用一组凭证(如用户名和密码)登录多个相关但独立的系统。
[Java实战]Spring Boot切面编程实现日志记录(三十六)
曼岛_的博客
05-27 1636
Spring Boot切面编程实现日志记录
Spring Boot养老院管理系统源码分享
幽络源
05-31 249
基于Spring Boot的养老院管理系统，详解后台设备管理及前台个人中心功能，助力养老机构信息化升级。
Spring Boot微服务架构（八）：开发之初就引入APM工具监控
软件行业技术文化交流。
05-28 1024
使用 APM（Application Performance Management）工具监控 Spring Boot 应用，可以帮助开发者实时追踪性能瓶颈、分析调用链路、监控资源使用情况，并快速定位故障。
Spring Boot启动慢？Redis缓存击穿？Kafka消费堆积？——Java后端常见问题排查实战
最新发布
yirenDM的博客
05-31 921
Java后端系统的问题排查离不开系统化思维和高效工具链。建议开发者熟练掌握JVM分析工具、链路追踪、监控报警、日志分析等能力。面对复杂业务场景，需结合技术栈深入理解各组件工作原理，快速定位并解决问题。持续总结排查经验，不断优化系统架构与运维流程，是保障稳定高可用服务的关键。本文面向Java开发者，系统梳理互联网大厂Java后端技术栈（含Spring Boot、Redis、Kafka等）在真实业务场景下的常见异常和性能问题，结合具体排查思路、工具、案例，帮助读者提升线上问题定位与系统调优能力。
基于Spring Boot+Vue 网上书城管理系统设计与实现(源码+文档+部署讲解）
再渺小的星光，也有属于它的光芒
05-30 839
技术范围：SpringBoot、Vue、SSM、HLMT、Jsp、PHP、Nodejs、Python、爬虫、数据可视化、小程序、安卓app、大数据、物联网、机器学习等设计与开发。主要内容：免费功能设计、开题报告、任务书、中期检查PPT、系统功能实现、代码编写、论文编写和辅导、论文降重、长期答辩答疑辅导、腾讯会议一对一专业讲解辅导答辩、模拟答辩演练、和理解代码逻辑思路。🍅文末获取源码联系🍅🍅文末获取源码联系🍅🍅文末获取源码联系🍅👇🏻 精彩专栏推荐订阅👇🏻 不然下次找不到哟。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

打赏作者

Clf丶忆笙

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

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

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

打赏作者

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

抵扣说明：

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

余额充值