使用 Swagger 注解创建通用组件

Question

我正在为我的 spring-boot 项目使用 swagger-annotation。

我想为控制器的每个资源返回一个通用响应代码合同。

在文档中：https://github.com/swagger-api/swagger-core/wiki/annotations#apiresponses-apiresponse 他们谈论 @ApiResponses 但我无法将注释放在类级别。

这是我所做的：

@Api(value = "Title",
    description = "What this controller is about"
)
@ApiResponses(value = { 
    @ApiResponse(code = 400, message = "Bad stuff from the client"),
    @ApiResponse(code = 404, message = "Item not found") }
    )
public class FooBarController {

      ...

}

但问题是400 - Bad stuff from the client和404 - Item not found永远不会显示在生成的文档中。

在 swagger 的官方文档中，我看到了这一部分：https ://swagger.io/docs/specification/describing-responses/#reuse

问题：如何使用java注释创建一种“可重用组件”？

谢谢

Answer 1

根据文档，您可以在文档级别执行此操作。

.useDefaultResponseMessages(false)
        .globalResponseMessage(RequestMethod.GET,
            newArrayList(new ResponseMessageBuilder()
                .code(400)
                .message("Bad stuff from the client")
                .build()))

https://springfox.github.io/springfox/docs/current/#springfox-spring-mvc-and-spring-boot

更新：

如果您想走注释路线，您可以创建自己的注释路线并将其放置在控制器上。

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@ApiResponses(value = { 
    @ApiResponse(code = 400, message = "Bad stuff from the client"),
    @ApiResponse(code = 404, message = "Item not found") }
    )
public @interface GlobalApiReponses {
}

然后用它..

@Api(value = "Title",
    description = "What this controller is about"
)
@GlobalApiReponses
public class FooBarController

多种方法的组合可能也是一个不错的选择。

@Target(ElementType.TYPE) 意味着您可以在类级别应用它。您可以使用 ElemenType.METHOD 对方法执行相同的操作。