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

我想提供一个＆＃34;样本＆＃34;作为JSON字符串的message参数的值（例如{"key" : "value"}）。有人知道如何使用Swagger注释做到这一点吗？我试过了

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

但它没有用。我想要的是一个＆＃34;样本值＆＃34;在文档中，读者可以单击以在文档中填充给定样本值的参数值字段。这可能吗？

以下是它的外观截图：

只是为了防止＆＃34;无用＆＃34;回答：由于我的业务逻辑，我无法将参数的类型从String更改为某个类类型。

Answer 1

不幸的是，您无法为原子参数（String，Number，...）提供示例或示例值。

如果参数是具有架构的对象，则只能提供示例，您只需要在属性说明中添加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 Boot用户，假设您具有REST方法，则接受json主体，但由于某些原因未明确使用@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;
}

这将生成带有可选标头x-locale和类型body的{{1}}的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中为请求参数提供样本值

3 个答案: