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 issue和其他一些与ApiResponses注释没有直接关系的SO questions，其中没有一个似乎提供了有效的解决方案。

使用Swagger UI 2.0我想让我们尝试一下，所以我做了以下

我创建了自定义注释GroupedApiResponses..
我用一组Swagger注释

GroupedApiResponses..

我在端点

GroupedApiResponses..

就像以前一样工作

见下文

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

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

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

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

1 个答案: