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。不幸的是，这些注释都不支持描述。

所以我的建议是：

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

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

注意：已经有annotation in spring适用于此。

创建您自己的ParameterBuilderPlugin
实现插件，如下所示

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;
  }
}

选择已应用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

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

4 个答案: