在 Swagger 中为请求参数提供示例值

Question

我在 Spring-Boot RestController 中有一个 rest 方法的方法签名，如下所示：

@RequestMapping(
        value = "/path",
        method = RequestMethod.POST,
        consumes = MediaType.APPLICATION_JSON_VALUE,
        produces = MediaType.APPLICATION_JSON_VALUE
)
@ApiImplicitParams({
        @ApiImplicitParam(
                name = "message", 
                value = "Message that is sent to the method", 
                required = true, 
                dataType = "string", 
                paramType = "body"
        )
})
public @ResponseBody String receiveMessage(@RequestBody String message) {
    // ...

    return "{\"success\": true}";
}

我想为 message 参数提供一个 "sample" 值，它是一个 JSON 字符串（例如 {"key" : "value"}）。有人知道我如何使用 Swagger 注释来做到这一点吗？我试过了

@ApiImplicitParams({
        @ApiImplicitParam(
                // ...
                example = "...JSON value..."
        )
})

但是没用。我想要的是文档中的 "sample value"，reader 可以单击以在文档中的参数值字段中填充给定的示例值。这可能吗？

下面是它的截图：

只是为了防止 "useless" 答案：由于我的业务逻辑，我无法将参数类型从 String 更改为某些 class 类型。

Answer 1

很遗憾，您无法为原子参数 a（字符串、数字等）提供样本或示例值。

如果参数是一个带有模式的对象，你只能提供一个例子，你只需要在属性描述中添加一个example 属性：

properties:
  firstName:
    description: first name
    type: string
    example: John

作为最后的手段，您可以在参数的描述中添加一个示例值（value 在 ApiImplicitParam 注释中）。

    @ApiImplicitParam(
            name = "message", 
            value = "Message that is sent to the method. Example: value", 
            required = true, 
            dataType = "string", 
            paramType = "body"
    )

Answer 2

对于 Spring 引导用户，假设您有一个 REST 方法，接受 json body，但由于某些原因没有明确使用 @RequestBody。按照以下步骤生成正确的 Swagger 文档

更新 SpringFox 附加模型的配置 bean

@Bean
public Docket apiDocket() {
     return new Docket(DocumentationType.SWAGGER_2)
             // ...
             .additionalModels(new TypeResolver().resolve(YourRequestModel.class));
}

为 @ApiImplicitParams

更新控制器 API

@PostMapping("/your-api")
@ApiOperation(value = "brief description", notes = "Greater details come here")
@ApiImplicitParams({
   @ApiImplicitParam(paramType = "header", name = "x-locale", example = "en"),
   @ApiImplicitParam(paramType = "body", dataType = "YourRequestModel")
})
public YourResponsetModel processRequest() {
   // ...
   return null;
}

这将为我们生成带有可选 header x-locale 和 YourRequestModel.

类型的 body 的 Swagger

Answer 3

你可以试试这个：

public MyObject myController(@ApiParam(example = "examplestring") @RequestParam("name") String name,
            @ApiParam(example = "1")@RequestParam("eventNo") int eventNo, @ApiParam(example = "2")@RequestParam("halRequestNo") int halRequestNo){

在 Swagger 中为请求参数提供示例值

Provide sample value for request parameter in Swagger

java

rest

swagger

spring-boot