使用Swagger注释创建通用组件

时间:2019-02-22 14:32:35

标签: swagger swagger-2.0

我在spring-boot项目中使用了swagger-批注。

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

在文档中: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 client404 - Item not found从未在生成的文档中显示。

在招摇的官方文档中,我看到了以下部分:https://swagger.io/docs/specification/describing-responses/#reuse

问题:如何创建带有Java注释的“可重用组件”?

谢谢

1 个答案:

答案 0 :(得分:2)

根据文档,您可以在“文件摘要”级别执行此操作。

.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对方法进行相同的操作。