将Swagger UI和ApiResponses批注与Java Spring端点一起使用时，如何干燥? [英] How to DRY when using Swagger UI and the ApiResponses annotations with Java Spring endpoints?

问题描述

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

I like Swagger because it makes your apis very user friendly. I use Swagger annotations like

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

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

On endpoints, query params, request params, request body and so on.

我喜欢保持我的POJO类整洁，总的来说，我会尽力遵循DRY规则，但是当我大摇大摆时，我发现自己不断重复重复如下图所示

I like to keep my POJO classes clean and in general I try my best to follow DRY rule however, when it comes to swagger I noticed that I keep repeating myself over and over as shown below

@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重演?

推荐答案

我在Google周围进行了一些搜索，并发现了与ApiResponses注释没有直接关系的SO问题，似乎都没有一个可行的解决方案.

I did some Googling around and came across this github issue and some other SO questions that are not directly related to ApiResponses annotations and none of them seem to present a working solution.

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

Using Swagger UI 2.0 I thought let's give it a try, so I did the following

1. 我创建了一个自定义注释GroupedApiResponses..
2. 我用一组Swagger注释对GroupedApiResponses..进行了注释
3. 我在端点顶部使用了GroupedApiResponses..批注
4. 像以前一样工作

1. I created a custom annotations GroupedApiResponses..
2. I annotated GroupedApiResponses.. with a group of Swagger annotations
3. I used the GroupedApiResponses.. annotations on top of endpoints
4. Works just like before

请参见下文

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

类似地(根据端点的结构和它返回的响应消息，您可以根据需要将注释分组到一个或多个自定义注释中)

Similarly (you can group annotations as you want in one or more than one custom annotation depending on structure of your endpoints and the response messages it return)

@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端点上的retrieveById和create端点上使用了上面的@GroupedApiResponsesAvecOk来代替@ApiResponses，并像以前一样工作.

And then I used the above @GroupedApiResponsesAvecOk on retrieveById and @GroupedApiResponsesAvecCreated on create endpoint in place of @ApiResponses and worked it just like before.

如上所示，与400, 404, 500有关的ApiResponse注释现在可以在其他端点之间重用.

As shown above, the ApiResponse annotations relating to 400, 404, 500 can now be reused across other endpoints.

这篇关于将Swagger UI和ApiResponses批注与Java Spring端点一起使用时，如何干燥?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！