2017-02-20 274 views
2

我在Spring Boot应用程序中使用Springfox Swagger2版本2.4.0,Springfox Swagger UI版本2.4.0和Swagger注解版本1.5.0。在Swagger UI中使用Springfox-Swagger2自定义请求头描述

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

在我的控制器API的代码片段是如下:

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

的扬鞭UI用于请求头是如下:

enter image description here

在图像中突出显示的矩形区域代表请求头的描述。

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

如何在Swagger UI中实现此目标,因为@RequestHeader注释只具有value,defaultValue,name和required属性?任何帮助将非常感激。

更新:寻找一个解决方案开箱没有我自己的

+0

不明白为什么这个问题是downvoted两次? – Gandhi

回答

3

TL的任何自定义注释; DR是,你将不得不建立自己的插件来做到这一点。

基本上,在这种情况下,为了增加描述的唯一开箱即用的注释是@ApiParam并且更准确@ApiImplicitParam。不幸的是,这些注释都不支持描述。

所以我的建议是:

  1. 创建您自己的注释,看起来像这样

    @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

    +0

    感谢您的快速回复。不要对你说的事情有太多的曝光,所以会尝试并回复你。再次感谢 – Gandhi

    +0

    终于有时间开始了。但我坚持一开始,因为我相当新的这一点。正如你所提到的,我尝试将描述注释放在我的请求头部参数中,并得到一个错误 - “注释类型不适用于这种声明”您能指导我吗?我也应该在我的春季应用程序代码中将测试类放在您的文章中?最后,我不是很清楚你在第4步中的含义请咨询 – Gandhi

    +0

    对此有何建议? – Gandhi

    1

    也许我的回答会帮助别人。

    Dilip Krishnanhis answer中,您可以使用io.swagger.annotations.ApiParamio.swagger.annotations.ApiImplicitParam Swagger批注用于精细调整的自定义文档。

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

    @ApiImplicitParam可以在API参数没有明确注册的情况下使用。

    @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"); 
        } 
    
    
    }  
    

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

    Swagger UI for custom method description

    +0

    我正在寻找一些要做的事情在请求头参数。不幸的是不是隐含的参数 – Gandhi

    +0

    描述已更新为常规请求参数。 –

    +0

    '@ApiParam(value =“header description”)'可以和'@ RequestHeader'一起使用来提供标题描述。 @DmytroBoichenko用这个更新答案。 –