如何使用org.eclipse.microprofile.openapi隐藏接口路径/服务？

DevOps 小满

2026-6-20

解决Quarkus中JAX-RS服务无法从OpenAPI文档隐藏的问题

问题根源

@Schema(hidden = true)注解的作用是隐藏数据模型（Schema），比如DTO类，而非API端点或整个JAX-RS资源类。你把它用在类或方法上，自然不会影响路径的显示。

正确的隐藏方式

针对Quarkus 3.12.3 + MicroProfile OpenAPI 3.1.1的环境，有两种可靠方案：

1. 使用`@Hidden`注解（推荐）

MicroProfile OpenAPI提供了专门的@Hidden注解，用于隐藏整个资源类或单个端点：

隐藏整个JAX-RS类：

import org.eclipse.microprofile.openapi.annotations.Hidden;
import jakarta.ws.rs.Path;

@Hidden
@Path("/internal-service")
public class InternalService {
    // 类内所有端点都会被隐藏
}

隐藏单个方法：

import org.eclipse.microprofile.openapi.annotations.Hidden;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/public-service")
public class PublicService {
    @GET
    @Path("/public-endpoint")
    public String publicEndpoint() {
        return "public content";
    }

    @Hidden
    @GET
    @Path("/internal-endpoint")
    public String internalEndpoint() {
        return "internal content";
    }
}

2. 通过配置文件批量过滤

如果需要批量隐藏符合特定路径规则的端点，可在application.properties中添加规则：

# 隐藏所有以/internal开头的路径
quarkus.smallrye-openapi.filter.paths.exclude=/internal/*

# 或者只保留特定路径，其余全部隐藏
quarkus.smallrye-openapi.filter.paths.include=/public/*

这种方式适合批量配置场景，基于路径匹配生效。