Spring boot执行器映射：添加端点描述| Spring Boot 3.3.0

Question

我在我的 spring boot 项目中使用 spring doc open api。 在我的休息控制器中，我有两个相同的端点，仅在参数和请求主体的内容上有所不同。 示例：

@PostMapping(value = "/v1/types", params = "type=typeA) 
...
@PostMapping(value = "/v1/types", params = "type=typeB)

由于 OpenAPI 规范，端点应该是唯一的，并且参数不被视为路径的一部分。所以 swagger ui 仅显示一个端点，我猜是按字母顺序排列的第一个端点。

就我而言，我的前端团队需要知道在我的 api 中使用哪些端点。因此，我找到了执行器 /mappings 端点的替代方案，它显示了我项目中的每个端点，这正是我所需要的。

我的问题是我需要为每个端点添加一些描述来描述需要哪些对象以及端点到底做什么。

有没有办法在 /actuator/mappings 中列出的端点下添加某种描述？

仅供参考：Spring Boot 3.3.0

使用 Swagger API 进行了很多尝试，例如向端点添加多个信息，例如使用 @Operation、@APIResponses 或 @Parameter 注释，但它无助于显示具有不同参数的相同端点。

我查看了官方的 Spring Boot Actuator 文档，但没有相关信息。

Answer 1

您可以使用如下所示的弹簧启动执行器，

在 pom.xml 中添加依赖项：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

创建自定义端点

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = "custommappings")
public class CustomMappingsEndpoint {

    @ReadOperation
    public Map<String, Object> customMappings() {
        Map<String, Object> mappings = new HashMap<>();

        Map<String, Object> typeAEndpoint = new HashMap<>();
        typeAEndpoint.put("path", "/v1/types");
        typeAEndpoint.put("params", "type=typeA");
        typeAEndpoint.put("description", "Handles type A requests.");

        Map<String, Object> typeBEndpoint = new HashMap<>();
        typeBEndpoint.put("path", "/v1/types");
        typeBEndpoint.put("params", "type=typeB");
        typeBEndpoint.put("description", "Handles type B requests.");

        mappings.put("typeAEndpoint", typeAEndpoint);
        mappings.put("typeBEndpoint", typeBEndpoint);

        return mappings;
    }
}

在 application.properties 中公开自定义端点

management.endpoints.web.exposure.include=custommappings

使用以下 URL 获取有关端点的信息，

http://server:port/context-path/actuator/custommappings

输出：

{"typeAEndpoint":{"path":"/v1/types","description":"Handles type A requests.","params":"type=typeA"},"typeBEndpoint":{"path":"/v1/types","description":"Handles type B requests.","params":"type=typeB"}}