Spring Boot 3.3.0：如何为Actuator /mappings端点添加接口描述？

针对你在Spring Boot 3.3.0中遇到的问题，以下几种方法可以为/mappings端点中的接口添加自定义描述：

方法1：使用Spring原生的@Description注解 #

Spring Framework 5.2+（包含Spring Boot 2.2+及3.x）提供了@Description注解，Actuator的/mappings端点会自动识别并展示该注解的内容。直接在控制器方法上添加即可：

import org.springframework.core.annotation.Description;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TypeController {

    @PostMapping(value = "/v1/types", params = "type=typeA")
    @Description("创建TypeA类型的资源，请求体需传入TypeADTO对象，用于实现XXX业务功能")
    public ResponseEntity<Void> createTypeA(@RequestBody TypeADTO dto) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }

    @PostMapping(value = "/v1/types", params = "type=typeB")
    @Description("创建TypeB类型的资源，请求体需传入TypeBDTO对象，用于实现YYY业务功能")
    public ResponseEntity<Void> createTypeB(@RequestBody TypeBDTO dto) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }
}

访问/actuator/mappings后，对应的handler条目会包含description字段，展示你配置的文本内容。

方法2：自定义注解+扩展Actuator映射描述提供者 #

如果需要更灵活的描述格式（比如同时包含功能说明、请求体信息等），可以自定义注解并扩展Actuator的MappingDescriptionProvider：

步骤1：定义自定义注解 #

import java.lang.annotation.*;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiEndpointInfo {
    // 接口功能描述
    String function();
    // 请求体说明
    String requestBody() default "";
}

步骤2：实现自定义MappingDescriptionProvider #

import org.springframework.boot.actuate.web.mappings.MappingDescriptionProvider;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import org.springframework.web.method.HandlerMethod;

@Component
public class CustomMappingDescProvider implements MappingDescriptionProvider {

    @Override
    public String getDescription(HandlerMethod handlerMethod) {
        // 获取自定义注解
        ApiEndpointInfo endpointInfo = AnnotationUtils.findAnnotation(handlerMethod.getMethod(), ApiEndpointInfo.class);
        if (endpointInfo != null) {
            StringBuilder descBuilder = new StringBuilder();
            descBuilder.append("功能：").append(endpointInfo.function());
            if (StringUtils.hasText(endpointInfo.requestBody())) {
                descBuilder.append(" | 请求体：").append(endpointInfo.requestBody());
            }
            return descBuilder.toString();
        }
        // 没有自定义注解时， fallback到@Description或方法名
        org.springframework.core.annotation.Description defaultDesc = handlerMethod.getMethodAnnotation(org.springframework.core.annotation.Description.class);
        return defaultDesc != null ? defaultDesc.value() : handlerMethod.getMethod().getName();
    }

    @Override
    public boolean supports(HandlerMethod handlerMethod) {
        return true;
    }
}

步骤3：在控制器方法上使用自定义注解 #

@PostMapping(value = "/v1/types", params = "type=typeA")
@ApiEndpointInfo(
        function = "创建TypeA类型资源，用于XXX业务场景",
        requestBody = "TypeADTO，包含name、code等必填字段"
)
public ResponseEntity<Void> createTypeA(@RequestBody TypeADTO dto) {
    // 业务逻辑
    return ResponseEntity.ok().build();
}

@PostMapping(value = "/v1/types", params = "type=typeB")
@ApiEndpointInfo(
        function = "创建TypeB类型资源，用于YYY业务场景",
        requestBody = "TypeBDTO，包含label、value等必填字段"
)
public ResponseEntity<Void> createTypeB(@RequestBody TypeBDTO dto) {
    // 业务逻辑
    return ResponseEntity.ok().build();
}

此时/mappings端点会展示你自定义的结构化描述内容。

额外补充：解决spring doc open API显示多端点的问题 #

虽然你选择了Actuator的/mappings，但可以通过配置让spring doc正确展示同路径不同params的接口：
给每个接口设置唯一的operationId（通过@Operation注解），同时调整spring doc配置：

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TypeController {

    @PostMapping(value = "/v1/types", params = "type=typeA")
    @Operation(
            operationId = "createTypeA",
            summary = "创建TypeA类型资源",
            description = "请求体为TypeADTO，包含XXX字段，用于实现XXX功能"
    )
    public ResponseEntity<Void> createTypeA(@RequestBody TypeADTO dto) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }

    @PostMapping(value = "/v1/types", params = "type=typeB")
    @Operation(
            operationId = "createTypeB",
            summary = "创建TypeB类型资源",
            description = "请求体为TypeBDTO，包含YYY字段，用于实现YYY功能"
    )
    public ResponseEntity<Void> createTypeB(@RequestBody TypeBDTO dto) {
        // 业务逻辑
        return ResponseEntity.ok().build();
    }
}

在application.yml中添加配置：

springdoc:
  swagger-ui:
    operations-sorter: alpha # 按字母排序展示端点
  api-docs:
    enabled: true

这样Swagger UI就能正确显示两个不同的端点，满足前端团队查看所有API的需求。

内容的提问来源于stack exchange，提问作者Nick M.