OpenAPI/Swagger-UI 注释和@BeanParam

Question

我正在使用 Quarkus 开发一组 JAX-RS 服务。我还使用 OpenAPI/Swagger-UI 注释对它们进行注释，以便轻松生成 API 文档。我可以像这样注释我的GET 服务...

    @Path("/{communityIdentifier}")
    @GET
    @Operation(summary = "Get community details", description = "Get detailed information about a community")
    @APIResponses({
            @APIResponse(responseCode = "200", description = "The community details", content = @Content(schema = @Schema(ref = "community"))),
            @APIResponse(name = "401", responseCode = "401", description = "Authentication required"),
            @APIResponse(name = "403", responseCode = "403", description = "Permission denied - you do not have access to access this resource", content = @Content(schema = @Schema(ref = "baseError"))),
            @APIResponse(name = "404", responseCode = "404", description = "Resource not found", content = @Content(schema = @Schema(ref = "baseError"))),
            @APIResponse(name = "500", responseCode = "500", description = "Internal service error", content = @Content(schema = @Schema(ref = "baseError"))) })
    @Timed(name = "getCommunityTimer")
    @Counted(name = "getCommunityCount")
    public Response getCommunity(
            @PathParam("securityRealm") @Parameter(name = "securityRealm", description = "The security realm name", required = true) String securityRealmName,
            @PathParam("communityIdentifier") @Parameter(name = "communityIdentifier", description = "The community identifier", required = true) String communityIdentifier) {
 // Stuff
}

当我访问我的 Swagger UI 端点时，我看到了该服务的详细记录条目，包括有关 securityRealm 和 communityIdentifier 参数的信息。现在我正在尝试以类似的方式创建 POST 和 PUT 方法，但遇到了问题。

由于我的PUT/POST 请求包含许多表单参数，我将它们封装到一个对象中并用@BeanParam 注释该方法。我的表单对象如下所示：

public class CommunityRequestForm extends AbstractRequestForm {

    private static final long serialVersionUID = 6007695645505404656L;

    @FormParam("description")
    private String description = null;

    @FormParam("name")
    private String name = null;

    public String getDescription() {
        return description;
    }

    public String getName() {
        return name;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public void setName(String name) {
        this.name = name;
    }

}

我的POST 方法如下所示：

    @Path("/")
    @POST
    @Consumes({ MediaType.APPLICATION_FORM_URLENCODED })
    @Operation(summary = "Create a community", description = "Creates a new community within a security realm")
    @APIResponses({
            @APIResponse(responseCode = "201", description = "The community details", content = @Content(schema = @Schema(ref = "community"))),
            @APIResponse(name = "401", responseCode = "401", description = "Authentication required"),
            @APIResponse(name = "403", responseCode = "403", description = "Permission denied - you do not have access to access this resource", content = @Content(schema = @Schema(ref = "baseError"))),
            @APIResponse(name = "404", responseCode = "404", description = "Resource not found", content = @Content(schema = @Schema(ref = "baseError"))),
            @APIResponse(name = "500", responseCode = "500", description = "Internal service error", content = @Content(schema = @Schema(ref = "baseError"))) })
    public Response createCommunity(
            @PathParam("securityRealm") @Parameter(name = "securityRealm", description = "The security realm name", required = true) String securityRealmName,
            @BeanParam CommunityRequestForm communityForm) {
  // Stuff
}

到目前为止，一切都很好。但是，我无法弄清楚如何注释 name 和 description 参数，因此它们由 OpenAPI/Swagger-UI 记录。我尝试将参数注释和定义更改为如下所示：

@FormParam("description")
@Parameter(name = "description", required = true, style = ParameterStyle.FORM)
private String description = null;

那什么也没做。我尝试将我的方法签名更改为如下所示：

public Response createCommunity(
            @PathParam("securityRealm") @Parameter(name = "securityRealm", description = "The security realm name", required = true) String securityRealmName,
            @Parameter(style = ParameterStyle.FORM) @BeanParam CommunityRequestForm communityForm)

还是什么都没有。我的问题是，有没有办法让 OpenAPI/Swagger-UI 注释很好地发挥作用并记录 @BeanParam 注释对象？还是根本不支持这种方法？

Answer 1

我知道他们通过以下 PR：https://github.com/smallrye/smallrye-open-api/pull/138 改进了 SmallRye OpenAPI 1.1.5 中的所有内容。

Quarkus 0.22.0 仍然使用 1.1.3。我们已经在 master 中更新到 1.1.8，所以即将发布的 0.23.0 将会有更新。

您可以尝试使用 Quarkus 主分支（只需使用 mvn clean install -DskipTests -DskipITs 构建它，然后将版本更改为 999-SNAPSHOT）。希望事情会变得更好。