使用Swagger UI和ApiResponses注释与Java Spring端点时如何干？

Question

我喜欢Swagger因为它使你的api非常用户友好.我使用Swagger像这样的注释

• @ApiParam
• @ApiResponse | @ApiResponses
• @ApiOperation
• 其他

在端点上,查询参数,请求参数,请求正文等.

我喜欢让我的POJO班级保持干净,但总的来说我会尽力遵循DRY规则,但是当谈到招摇时,我注意到我一遍又一遍地重复自己,如下图所示

@ApiOperation(value = "Retrieve object by id")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "OK"),
    @ApiResponse(code = 404, message = "Not Found"),
    @ApiResponse(code = 400, message = "Bad Request"),
    @ApiResponse(code = 500, message = "ISE")
})
public Response retrieveById(@ApiParam(value = "Some id") @PathParam("sid") int id) {       
}

@ApiOperation(value = "Create object")
@ApiResponses(value = {
    @ApiResponse(code = 201, message = "Created"),
    @ApiResponse(code = 404, message = "Not Found"),
    @ApiResponse(code = 400, message = "Bad Request"),
    @ApiResponse(code = 500, message = "ISE")
})
public Response create(@ApiParam(value = "Request body") RequestBody body) {
}

如何避免重复自己Swagger annotations？

Answer 1

我做了一些谷歌搜索,遇到了这个github问题和其他一些与注释没有直接关系的SO问题,ApiResponses但似乎没有一个问题能够提供一个有效的解决方案.

使用Swagger UI 2.0 我认为让我们尝试一下,所以我做了以下

1. 我创建了一个自定义注释 GroupedApiResponses..
2. 我GroupedApiResponses..用一组Swagger注释注释
3. 我GroupedApiResponses..在端点上使用了注释
4. 就像以前一样工作

见下文

package com.raf.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Ok"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 400, message = "Bad Request"),
        @ApiResponse(code = 500, message = "ISE") 
})
public @interface GroupedApiResponsesAvecOk {
}

同样(您可以根据端点的结构和返回的响应消息,在一个或多个自定义注释中根据需要对注释进行分组)

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@ApiResponses(value = {
        @ApiResponse(code = 201, message = "Created"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 400, message = "Bad Request"),
        @ApiResponse(code = 500, message = "ISE") 
})
public @interface GroupedApiResponsesAvecCreated {
}

然后我使用上面的@GroupedApiResponsesAvecOkon retrieveById和@GroupedApiResponsesAvecCreatedon create端点来代替@ApiResponses和以前一样工作.

如上所示,现在可以跨其他端点重复使用与ApiResponse注释相关的注释400, 404, 500.