当使用Swagger UI和带有Java Spring端点的ApiResponses注释时，如何干燥？

java spring swagger swagger-2.0 swagger-ui

2022-09-03 06:58:17

我喜欢，因为它使您的api非常用户友好。我使用像这样的注释SwaggerSwagger

@ApiParam
@ApiResponse |@ApiResponses
@ApiOperation
别人

在终结点上，查询参数、请求参数、请求正文等。

我喜欢保持我的课程干净，总的来说，我尽力遵循规则，但是，当涉及到摇摆不定时，我注意到我一遍又一遍地重复自己，如下所示POJODRY

@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

答案 1

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

使用我想让我们试一试，所以我做了以下事情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 {
}

然后，我在端点上和端点上使用了上述内容来代替它，并像以前一样使用它。@GroupedApiResponsesAvecOkretrieveById@GroupedApiResponsesAvecCreatedcreate@ApiResponses

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

答案 2