如何将 "Example Value" 添加到 Swagger 中的参数

Question

我正在创建一个新的 Rest API 和 Spring Boot 使用 Swagger 来记录它，我无法更改 Web 上显示的示例值。我可以在模型中更改它，但不能在 POST 参数中更改。

这些是我的依赖项：

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.4.RELEASE</version>
        <relativePath/>
        <!-- lookup parent from repository -->
    </parent>
...
        <swagger.version>2.9.2</swagger.version>
...
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
...

我的代码是：

    @PostMapping("events")
    @ApiOperation(value = "Get events")
    public ResponseEntity<List<Event>> events(
            @ApiParam(value = "Event type", required = true, example = "sent") final @RequestBody String type) {
        return new ResponseEntity<List<Event>>(getEvents.get(type), HttpStatus.OK);
    }

请参阅 'string'。

，而不是示例值 'sent'

此注释适用于事件模型，但不适用于此处。

我错过了什么？

Answer 1

根据 @ApiParam 的文档 - example 属性是

a single example for non-body type parameters

但是您为字符串参数使用了 @RequestBody 注释。在您的情况下：将 @RequestBody 注释更改为 @RequestParam 并且您应该能够在 Swagger UI:

中看到提供的示例

@PostMapping("events")
@ApiOperation(value = "Get events")
public ResponseEntity<List<Event>> events(
    @ApiParam(value = "Event type", required = true, example = "sent") final @RequestParam String type) {
        return new ResponseEntity<List<Event>>(getEvents.get(type), HttpStatus.OK);
    }

对于正文参数，有 examples 属性。查看Springfox Reference Documentation如何使用它。

...
examples = @io.swagger.annotations.Example(
        value = {
            @ExampleProperty(value = "{'property': 'test'}", mediaType = "application/json")
        })) 
}
...

如何将 "Example Value" 添加到 Swagger 中的参数

How to add "Example Value" to a parameter in Swagger

swagger

swagger-ui

spring-boot

springfox