使用 Springfox-Swagger2 在 Swagger UI 中自定义请求头描述 [英] Customizing Request Header description in Swagger UI using Springfox-Swagger2

问题描述

我在 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 属性?任何帮助将不胜感激.

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

解决方案

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

正如在

I am using Springfox Swagger2 version 2.4.0, Springfox Swagger UI version 2.4.0 and Swagger Annotations version 1.5.0 in my Spring Boot application.

The question here is, I am able to generate swagger UI for my controller's API and I am able to test the same. But I am not able to specify request header description for my request header. I m using @RequestHeader annotation for the same.

The code snippet in my controller API is follows:

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

The Swagger UI for the request header is as follows:

The highlighted rectangular area in the image represents the description of the request header.

Currently it just picks up the data mentioned in the name attribute and shows it. But i wanna give a different description for the same. i.e. "Value of license key"

How can i achieve this in Swagger UI as @RequestHeader annotation only have value, defaultValue, name and required attributes? Any help would be really appreciated.

Update: Looking for a solution out of the box without any custom annotation of my own

解决方案

Maybe my answer will help somebody.

As mentioned Dilip Krishnan in his answer you could use io.swagger.annotations.ApiParam or io.swagger.annotations.ApiImplicitParam Swagger annotations for fine-tuned custom documentation.

@ApiParam could be used for registered method parameters.

@ApiImplicitParam could be used if API parameter wasn't registered explicitly.

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


}    

And in the end you could see following picture

这篇关于使用 Springfox-Swagger2 在 Swagger UI 中自定义请求头描述的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！