如何利用Quarkus组件自动填充OpenAPI路径项对象的summary与description？

你可以通过以下两种无需手动编写完整OpenAPI规范的方式，为Path Item Object填充summary和description字段：

1. 使用SmallRye OpenAPI的@PathItem注解 #

这是最直接的方式，通过在JAX-RS资源类上添加@PathItem注解，直接指定该路径的摘要和描述。

代码示例 #

import org.eclipse.microprofile.openapi.annotations.PathItem;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.GET;
import java.util.List;

@Path("/users")
@PathItem(
    summary = "用户资源管理接口集合",
    description = "提供用户的创建、查询、更新、删除等完整CRUD操作，支持分页、筛选等高级查询"
)
public class UserResource {

    @GET
    public List<User> listAllUsers() {
        // 业务逻辑实现
        return List.of();
    }

    // 其他接口方法...
}

2. 利用JavaDoc自动生成 #

quarkus-smallrye-openapi扩展默认会扫描资源类的JavaDoc注释，将其转换为Path Item的description。如果需要同时设置summary，可以结合@PathItem注解的summary属性，或者让JavaDoc的第一行作为summary、后续内容作为description（默认开启JavaDoc扫描功能）。

代码示例 #

import jakarta.ws.rs.Path;
import jakarta.ws.rs.GET;
import java.util.List;
import org.eclipse.microprofile.openapi.annotations.PathItem;

/**
 * 用户资源管理接口集合
 * <p>
 * 提供用户的创建、查询、更新、删除等完整CRUD操作，支持分页、筛选等高级查询
 * </p>
 */
@Path("/users")
@PathItem(summary = "用户资源管理") // 注解指定summary，JavaDoc作为description
public class UserResource {

    @GET
    public List<User> listAllUsers() {
        return List.of();
    }
}

验证方式 #

启动Quarkus应用后，访问/q/openapi端点，即可查看生成的OpenAPI v3规范，对应paths下的目标路径节点会包含你配置的summary和description字段。

注意事项 #

• 确保项目已正确引入quarkus-smallrye-openapi依赖（Maven/Gradle均可）。
• @PathItem注解属于MicroProfile OpenAPI规范，由quarkus-smallrye-openapi扩展原生支持，无需额外引入其他依赖。

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