从 java 生成 Swagger UI，为 RequestBody 提供示例不起作用

Question

如何在 Swagger UI 中提供请求正文的示例？ 我使用 Springboot 作为框架。 这是重现问题的最小java代码：

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;

@RestController
@RequestMapping("/api/my/problem")
public class MyProblemResource {

    @PostMapping(value = "/")
    @Operation(summary = "Create person")
    public ResponseEntity<PersonDTO> getPerson(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                    description = "the person you want to create, in json format",
                    content = @Content(examples = @ExampleObject( value = "foobar"))
                    )
            @RequestBody PersonDTO person){
        return ResponseEntity.ok().build();
    }
}

class PersonDTO{
    String firstName;
    String lastName;
    public PersonDTO() {}
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
}

所以我希望字符串“foobar”出现在生成的 Swagger UI 中，但它没有： 黑框中的文字应该是“foobar”

编辑：我还尝试按照https://stackoverflow.com/users/1076463/robin的建议将注释放在方法级别，如下所示：https://pastebin.com/FPGHuYKd，仍然没有运气。

顺便说一句，这些注释来自我的 Maven pom.xml 中的依赖项：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

Answer 1

有一个名为

@RequestBody

的 Spring 框架注释，还有一个名为

@RequestBody

的 swagger 注释。 您必须同时提供两者。

spring 注解告诉 spring 它需要知道什么。

swagger注解测试swagger需要知道什么。 您可以在其中提供 swagger API 文档的示例。

据我所知，提供两个同名注释的唯一方法是完全限定冲突的注释。

假设一个 API 使用 JSON 输入和输出，下面是一个混合了 spring 和 swagger 注释的示例。 特别注意

RequestBody

注释：

@RestController
@RequestMapping("/path/v1")
public class PathControllerV1 {
    @PostMapping(value = "/stuff", produces = MediaType.APPLICATION_JSON_VALUE)
    @Operation(description = "path/v1/stuff endpoint description")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "202", description = "accepted"),
        @ApiResponse(responseCode = "400", description = "bad request")
    })
    @ResponseStatus(HttpStatus.ACCEPTED)
    @ResponseBody
    public OutputObjectType postStuffHandler(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                content = @Content(examples = @ExampleObject(value = "{ example json }")))
            @org.springframework.web.bind.annotation.RequestBody
            InputObjectType postBody)
    {
        // do something with postBody and return an OutputObjectType
    }
}