OpenAPI / Swagger-UI注释和@BeanParam

Question

I am developing a set of JAX-RS services using Quarkus. I'm also annotating them with the OpenAPI/Swagger-UI annotations for easy generation of API documentation. I'm able to annotate my GET services like so...

    @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
}

When I access my Swagger UI endpoint, I see nicely documented entries for this service, including information on the securityRealm and communityIdentifier parameters. Now I am trying to create POST and PUT methods in a similar manner and am running into an issue.

Since my PUT / POST requests contain a number of form parameters, I'm encapsulating them into an object and annotating the method with @BeanParam . My form object looks like this:

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;
    }

}

My POST method looks like this:

    @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
}

So far, so good. However, I have not been able to figure out how to annotate the name and description parameters so they are documented by OpenAPI/Swagger-UI. I tried changing the parameter annotations and definition to look like this:

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

That did nothing. I tried changing my method signature to look like this:

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

Still nothing. My question is, is there a way to get the OpenAPI/Swagger-UI annotations to play nicely and document a @BeanParam annotated object? Or is this approach not supported at all?

Answer 1

I know they improved all that in SmallRye OpenAPI 1.1.5 with this PR: https://github.com/smallrye/smallrye-open-api/pull/138 .

Quarkus 0.22.0 still uses 1.1.3. We have updated to 1.1.8 in master so the soon to be released 0.23.0 will have the update.

You can try with the Quarkus master branch (just build it with mvn clean install -DskipTests -DskipITs then change the version to 999-SNAPSHOT ). Hopefully, things will be better.