Spring集成Camunda时多Swagger文档展示配置异常问题

数据老陈

2026-6-22

解决Spring集成Camunda时双Swagger文档显示问题

问题分析

配置springdoc.swagger-ui.urls[0]后自定义文档消失，是因为手动指定urls集合会覆盖springdoc自动生成的默认API文档；而设索引1绑定失败，是因为springdoc.swagger-ui.urls本质是Set集合，不支持数组索引访问语法，强行使用会导致绑定错误。

解决方案

要同时保留自定义API文档和Camunda的Swagger文档，可通过以下两种方式配置：

1. 配置文件显式声明（推荐）

在application.properties中直接重复配置键名，Set集合会自动收集所有项，无需索引：

# 配置Camunda的Swagger文档
springdoc.swagger-ui.urls.name=Camunda
springdoc.swagger-ui.urls.url=/path/to/camunda-swagger.json
# 配置自定义API的Swagger文档（默认地址为/v3/api-docs）
springdoc.swagger-ui.urls.name=自定义API
springdoc.swagger-ui.urls.url=/v3/api-docs

2. Java配置类扩展控制

如果需要更灵活的逻辑，可创建配置类手动注册文档项：

import org.springdoc.core.properties.AbstractSwaggerUiConfigProperties;
import org.springdoc.core.properties.SwaggerUiConfigProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerUiCustomConfig {

    @Bean
    public SwaggerUiConfigProperties swaggerUiConfigProperties() {
        SwaggerUiConfigProperties properties = new SwaggerUiConfigProperties();
        // 添加Camunda文档
        properties.getUrls().add(new AbstractSwaggerUiConfigProperties.SwaggerUrl("Camunda", "/path/to/camunda-swagger.json", null));
        // 添加自定义API文档
        properties.getUrls().add(new AbstractSwaggerUiConfigProperties.SwaggerUrl("自定义API", "/v3/api-docs", null));
        return properties;
    }
}