Spring OpenAPI：如何覆盖Actuator的默认标签与描述？

可以覆盖Actuator端点在OpenAPI文档中的默认命名标签和描述，下面是两种实用的实现方式：

1. 单个端点自定义：通过包装原生端点添加注解 #

创建自定义Controller包装原生Actuator端点，使用@Operation注解直接指定自定义的摘要和描述，同时保留原端点的功能。

示例代码（以health端点为例）：

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

@RestController
public class CustomHealthEndpoint {

    private final HealthEndpoint healthEndpoint;

    public CustomHealthEndpoint(HealthEndpoint healthEndpoint) {
        this.healthEndpoint = healthEndpoint;
    }

    @GetMapping("/actuator/health")
    @Operation(summary = "服务健康状态检查", description = "获取当前应用的详细健康状态，包含各依赖组件的健康情况")
    public Object customHealth() {
        return healthEndpoint.health();
    }
}

如果需要避免与原生端点冲突，可以修改自定义端点的路径，或者通过management.endpoints.web.exposure.exclude配置禁用原生端点的Web暴露。

2. 全局批量修改：实现OpenApiCustomizer接口 #

如果需要批量修改多个Actuator端点的描述，可实现OpenApiCustomizer接口，遍历OpenAPI文档中的路径，找到对应Actuator端点并修改其元数据。

示例代码：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.PathItem;
import org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties;
import org.springframework.boot.actuate.endpoint.web.PathMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springdoc.core.customizers.OpenApiCustomizer;

import java.util.Map;

@Configuration
public class ActuatorOpenApiConfig {

    private final WebEndpointProperties webEndpointProperties;
    private final PathMapper pathMapper;

    public ActuatorOpenApiConfig(WebEndpointProperties webEndpointProperties, PathMapper pathMapper) {
        this.webEndpointProperties = webEndpointProperties;
        this.pathMapper = pathMapper;
    }

    @Bean
    public OpenApiCustomizer actuatorOpenApiCustomizer() {
        return openApi -> {
            String actuatorBasePath = webEndpointProperties.getBasePath();
            Map<String, PathItem> paths = openApi.getPaths();

            // 修改health端点
            PathItem healthPath = paths.get(actuatorBasePath + "/health");
            if (healthPath != null && healthPath.getGet() != null) {
                Operation healthOp = healthPath.getGet();
                healthOp.setSummary("服务健康状态检查");
                healthOp.setDescription("查询应用整体健康状态，包含数据库、缓存等依赖组件的健康详情");
            }

            // 修改info端点
            PathItem infoPath = paths.get(actuatorBasePath + "/info");
            if (infoPath != null && infoPath.getGet() != null) {
                Operation infoOp = infoPath.getGet();
                infoOp.setSummary("应用元信息查询");
                infoOp.setDescription("获取应用的版本号、构建时间、环境配置等元数据");
            }

            // 可添加更多端点的修改逻辑
        };
    }
}

注意事项 #

• 确保项目已引入SpringDoc OpenAPI依赖（如Spring Boot 3+使用springdoc-openapi-starter-webmvc-ui，Spring Boot 2.x使用springdoc-openapi-ui）
• Spring Boot版本不同，对应的OpenAPI注解和配置类可能存在差异，需根据实际版本调整
• 全局修改方式需要准确匹配Actuator端点的路径，可通过management.endpoints.web.base-path配置调整基础路径

内容的提问来源于stack exchange，提问作者Bruce_Wayne