java - 在 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 参数提供一个“样本”值，它是一个 JSON 字符串(例如 {"key": "value"})。有人知道我如何使用 Swagger 注释来做到这一点吗？我试过了

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

但是没有用。我想要的是文档中的“示例值”，读者可以单击该文档中的参数值字段来填充给定的示例值。这可能吗？

这是它可能看起来的截图:

只是为了防止“无用”的答案:由于我的业务逻辑，我无法将参数类型从 String 更改为某个类类型。

Answer 1

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

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

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

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

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