java OpenAPI/SwaggerUI注释和@BeanParam
我正在使用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
注释的对象?还是根本不支持这种方法
共 (0) 个答案