主页 / coding / 问题 / 79275521
Accepted
nik0x1
Asked: 2024-12-12 22:42:20 +0800 CST

OpenAPI 路径项对象的摘要和描述

  • 772

quarkus-rest我正在使用Jakarta REST（以前称为 JAX-RS）的实现来开发 REST API 。我还使用quarkus-smallrye-openapi扩展来生成我的 API 规范（OpenAPI v3）。

我如何填写字段：使用注释或其他方式（无需手动编写规范）的路径项对象的摘要和描述？

java

2 个回答

  1. Best Answer

    实际上，使用标准注释无法做到这一点。您有几个选项，包括使用静态 OpenAPI 文件或实现OASFilter添加摘要和/或说明。

    静态 OpenAPI

    放置一个openapi.yaml或（对于 Maven 项目，在 内openapi.json），您可以仅定义您关心的 及其描述。此文件将与注释扫描的结果合并。META-INFsrc/main/resourcespaths

    paths:
  "/foo":
    summary: "...",
    description: "..."
  "/foo/{bar}":
    summary: "...",
    description: "..."

    OASFilter执行

    编写一个实现，org.eclipse.microprofile.openapi.OASFilter并通过将完全限定类名设置为属性的值来配置它mp.openapi.filter。您可以用任何您想要的逻辑覆盖方法filterPathItem以设置属性。例如，您可以通过首先从中获取来从配置属性中查找Config它们ConfigProvider。

    class MyFilter implements OASFilter {
    @Override
    public PathItem filterPathItem(PathItem pathItem) {
        // Logic to set the summary or description on pathItem goes here.
        return pathItem;
    }
}
    • 2

  2. 您可以使用注释做这样的事情：

    @GET
@Path("options/{foo}")
public Response getFoo(
   @Schema(description = "some desc.",required = true)
   @PathParam("foo") String foo
) {
....

    或者您可以通过将 openapi.yaml 放入 resources/META-INF 中来合并/扩展/丰富生成的 openapi 规范。

    在路径上项目执行以下操作：

    @GET
@Path("search")
@Operation(operationId = "SearchFoo", summary = "Search Foos", description = "Search Foos by status and date")
   public Foo searchFoo...
    • -1

相关问题