How to DRY when using Swagger UI and the ApiResponses annotations with Java Spring endpoints?(使用 Swagger UI 和带有 Java Spring 端点的 ApiResponses 注释时如何干燥?)
问题描述
I like Swagger
because it makes your apis very user friendly. I use Swagger
annotations like
- @ApiParam
- @ApiResponse | @ApiResponses
- @ApiOperation
- Others
On endpoints, query params, request params, request body and so on.
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) {
}
How to avoid repeating yourself with Swagger annotations
?
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.
Using Swagger UI 2.0
I thought let's give it a try, so I did the following
- I created a custom annotations
GroupedApiResponses..
- I annotated
GroupedApiResponses..
with a group of Swagger annotations - I used the
GroupedApiResponses..
annotations on top of endpoints - Works just like before
See below
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 {
}
And then I used the above @GroupedApiResponsesAvecOk
on retrieveById
and @GroupedApiResponsesAvecCreated
on create
endpoint in place of @ApiResponses
and worked it just like before.
As shown above, the ApiResponse
annotations relating to 400, 404, 500
can now be reused across other endpoints.
这篇关于使用 Swagger UI 和带有 Java Spring 端点的 ApiResponses 注释时如何干燥?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持编程学习网!
本文标题为:使用 Swagger UI 和带有 Java Spring 端点的 ApiResponses 注释时如何干燥?
基础教程推荐
- 如何使用 Eclipse 检查调试符号状态? 2022-01-01
- 首次使用 Hadoop,MapReduce Job 不运行 Reduce Phase 2022-01-01
- 如何在不安装整个 WTP 包的情况下将 Tomcat 8 添加到 Eclipse Kepler 2022-01-01
- Spring Boot Freemarker从2.2.0升级失败 2022-01-01
- Java 中保存最后 N 个元素的大小受限队列 2022-01-01
- 在螺旋中写一个字符串 2022-01-01
- 由于对所需库 rt.jar 的限制,对类的访问限制? 2022-01-01
- 如何对 HashSet 进行排序? 2022-01-01
- 如何使用 Stream 在集合中拆分奇数和偶数以及两者的总和 2022-01-01
- 如何强制对超级方法进行多态调用? 2022-01-01