在Quarkus中如何为OpenAPI标记JAX-RS资源方法为已弃用？

我之前也踩过这个坑——Java自带的@Deprecated注解是给Java生态（编译器、IDE）用的，MicroProfile OpenAPI默认不会把它映射到OpenAPI规范里的deprecated字段。要实现你想要的效果，得用MicroProfile OpenAPI提供的专属注解来处理，下面是两种靠谱的方法：

方法一：使用@Operation注解直接标记 #

这是最直接的方式，给目标JAX-RS资源方法添加@Operation注解，并设置deprecated = true属性。示例代码如下：

import org.eclipse.microprofile.openapi.annotations.Operation;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/sample")
public class SampleResource {

    @GET
    @Operation(
        summary = "获取示例数据",
        description = "这个接口已经不再推荐使用，请使用新的/v2/sample接口",
        deprecated = true
    )
    public String getSampleData() {
        return "legacy data";
    }
}

添加这个注解后，生成的OpenAPI JSON中对应的get方法就会自动带上"deprecated": true的标记，完全符合你的需求。

方法二：通过静态OpenAPI文件补充（适合批量配置） #

如果你的项目里有多个接口需要标记弃用，或者想统一管理OpenAPI文档，也可以通过静态的openapi.yaml或openapi.json文件来配置。在src/main/resources/META-INF目录下创建文件，然后补充对应的弃用配置：

openapi: 3.0.3
paths:
  /sample:
    get:
      summary: "获取示例数据"
      deprecated: true
      responses:
        '200':
          description: "成功返回数据"
          content:
            text/plain:
              schema:
                type: string

不过这种方式需要注意和代码注解的兼容性，Quarkus会合并静态文件和代码注解生成最终的OpenAPI文档。

前置条件：确保依赖正确 #

别忘了在你的pom.xml（Maven）或build.gradle（Gradle）中添加Quarkus的OpenAPI扩展依赖，否则相关注解不会生效：

<!-- Maven 依赖 -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

启动应用后，访问/q/openapi端点就能看到生成的OpenAPI文档，里面对应的接口已经标记为弃用啦。

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