使用 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 中的代码 sn-p 如下：

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

请求头的Swagger UI如下：

图片中高亮的矩形区域代表请求头的描述。

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

我如何在 Swagger UI 中实现这一点，因为 @RequestHeader 注释只有值、默认值、名称和必需的属性？任何帮助将不胜感激。

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

Answer 1

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

正如his answer 中提到的Dilip Krishnan，您可以使用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。

1. 创建您自己的ParameterBuilderPlugin
2. 如下图实现插件

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 ..

这个想法是将“描述”字段添加到生成的招摇中。它可能看起来很老套，但它是一种快速简单的解决方案，对您的个人情况很有用。

Answer 4

快速、简单有效的解决方案是使用enum，例如：

@RequestHeader(value = "someval") ALLOWED_VALUES input

private enum ALLOWED_VALUES {A, B, C};

以下内容将大摇大摆地显示： 可用值：A, B, C