使用Springfox-Swagger2在Swagger UI中自定义请求标头描述

Question

我在Spring Boot应用程序中使用Springfox Swagger2版本2.4.0，Springfox Swagger UI版本2.4.0和Swagger Annotations版本1.5.0。

这里的问题是，我能够为我的控制器的API生成swagger UI，我能够测试相同的。但是我无法为我的请求标头指定请求标头描述。我使用@RequestHeader注释。

我的控制器API中的代码段如下：

@RequestHeader(name = "Api-Key") String apiKey

请求标头的Swagger UI如下：

图像中突出显示的矩形区域表示请求标题的描述。

目前它只是获取name属性中提到的数据并显示它。但是我想给出不同的描述。即“许可证密钥的价值”

我如何在Swagger UI中实现这一点，因为@RequestHeader注释只有value，defaultValue，name和required属性？任何帮助将非常感激。

更新：寻找一个开箱即用的解决方案，没有任何我自己的自定义注释

Answer 1

也许我的回答会对某人有所帮助。

正如Dilip Krishnan中提到的his answer，您可以使用io.swagger.annotations.ApiParam或io.swagger.annotations.ApiImplicitParam Swagger注释来进行微调自定义文档。

@ApiParam可用于注册的方法参数。

如果未明确注册API参数，则可以使用@ApiImplicitParam。

@RestController
@RequestMapping(value = "/v1/test", produces = "application/json")
@Api(value = "/v1/test")
public class TestController {

    @ApiOperation(value = "Do Something method", tags = "Test method")
    @RequestMapping(value = "/doSomeThing", method = RequestMethod.GET)
    public Foo doSomeThing(
            @ApiParam(value = "Param1 Description", required = true)
            @RequestParam String param) {
        throw new UnsupportedOperationException("do Some Things");
    }

    @ApiOperation(value = "Do Something Another method", tags = "Test method")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "anotherParam1", value = "Another Param1 Description", paramType = "header"),
            @ApiImplicitParam(name = "anotherParam1", value = "Another Param1 Description", paramType = "header")
    })
    @RequestMapping(value = "/doSomeThingAnother", method = RequestMethod.GET)
    public Foo doSomeThingAnother(Bar bar) {
        throw new UnsupportedOperationException("do Some Thing Another");
    }


}    

最后你可以看到下面的图片

Answer 2

TL; DR是你必须建立自己的插件才能做到这一点。

基本上，在这种情况下唯一的开箱即用注释来增强描述是@ApiParam和更准确的@ApiImplicitParam。不幸的是，这些注释都不支持描述。

所以我的建议是：

1. 创建自己的注释，如下所示

   @RequestHeader(name = "Api-Key")
    @Description("Value of license key") String apiKey

注意：已经有一个适合这种情况的annotation in spring。

2. 创建自己的ParameterBuilderPlugin
3. 实现插件，如下所示

public class Test implements ParameterBuilderPlugin {
  @Override
  public void apply(ParameterContext parameterContext) {
    ResolvedMethodParameter methodParameter =parameterContext.resolvedMethodParameter();
    Optional<Description> requestParam = methodParameter.findAnnotation(Description.class);
    if (requestParam.isPresent()) {
      parameterContext.parameterBuilder()
        .description(requestParam.get().value());
    }
  }

  @Override
  public boolean supports(DocumentationType documentationType) {
    return false;
  }
}

4. 选择已经处理的the order应用的after swagger annotations值。

还请将springfox库升级到latest version。

Answer 3

我们遇到了同样的问题，并通过以下方式解决了问题：

.. @RequestHeader(value = "..") @ApiParam(value = "Description") String param ..

我们的想法是将“description”字段添加到生成的swagger中。它可能看起来很简陋，但它是一个快速简单的解决方案，可以在您的个人情况下使用。