在Swagger UI中使用Springfox-Swagger2自定義請求頭描述

Question

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

這裏的問題是，我能夠爲我的控制器的API生成swagger UI，並且我能夠測試相同。但是我無法爲我的請求標題指定請求標題描述。我使用@RequestHeader註解相同。

在我的控制器API的代碼片段是如下：

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

的揚鞭UI用於請求頭是如下：

在圖像中突出顯示的矩形區域代表請求頭的描述。

目前它只是拿起name屬性中提到的數據並顯示它。但我想給出不同的描述。即「許可證密鑰的價值」

如何在Swagger UI中實現此目標，因爲@RequestHeader註釋只具有value，defaultValue，name和required屬性？任何幫助將非常感激。

更新：尋找一個解決方案開箱沒有我自己的

Answer 1

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。

Answer 2

也許我的回答會幫助別人。

如Dilip Krishnan在his answer中，您可以使用io.swagger.annotations.ApiParam或io.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"); 
    } 


}  

而在最後，你可以看到下面的圖片