java - 将 Swagger UI 和 ApiResponses 注释与 Java Spring 端点一起使用时如何进行 DRY？

Question

我喜欢 Swagger，因为它使您的 API 对用户非常友好。我使用 Swagger 注释，例如

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

关于端点、查询参数、请求参数、请求正文等。

我喜欢保持我的 POJO 类干净，通常我会尽力遵循 DRY 规则，但是，当谈到 Swagger 时，我注意到我保持 一遍又一遍地重复自己，如下所示

@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 注释 重复自己？

Answer 1

我在谷歌上搜索了一下，发现了这个 github issue和其他一些SO questions与 ApiResponses 注释没有直接关系，并且它们似乎都没有提供有效的解决方案。

使用 Swagger UI 2.0 我想试试看，所以我做了以下操作

1. 我创建了一个自定义注释 GroupedApiResponses..
2. 我用一组 Swagger 注释注释了 GroupedApiResponses..
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 {
}

然后我在 retrieveById 上使用上面的 @GroupedApiResponsesAvecOk 和在 create 端点上使用 @GroupedApiResponsesAvecCreated 代替@ApiResponses 并像以前一样工作。

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