如何在 Spring Boot 中在 Swagger UI 中拥有一组示例

Question

目前，我使用 Swagger v2 来显示控制器类的端点（我使用 Docket 在 Spring Boot 中配置 swagger）。但是由于请求体中字段的数量，返回会受到影响 --> 我需要在 Swagger UI 中有示例。

有没有办法在 Swagger UI 中提供示例列表，例如：

//This is Swagger UI//
//Endpoint 1//
Body for get a user with name:
{
  "username": "cron"
}

Body for get user in domain:
{
  "username": "cron",
  "domain": "IT"
}

非常感谢！

Answer 1

如何在 Spring Boot 中在 Swagger UI 中拥有一组示例

您可以使用注释为整个操作设置示例：

@Operation(
    summary = "Create a new user",
    examples = @Example(
        value = @ExampleObject("{ \"username\": \"cron\", \"domain\": \"IT\" }"),
        summary = "Example 1"
    ),
    examples = @Example(
        value = @ExampleObject("{ \"username\": \"mary\", \"domain\": \"Sales\" }"),
        summary = "Example 2"
    )
)

或者您可以为您的请求正文设置完整的示例：

public User createUser(@RequestBody @ExampleObject(value = "{ \"username\": \"cron\", \"domain\": \"IT\" }") User user) {

但是

@ExampleObject

仅支持原始类型或字符串的请求正文参数。

否则，您可以在请求正文类中的每个字段上使用

@ExampleProperty

注释：

public class User {

  @ExampleProperty(value = "cron")
  private String username;

  @ExampleProperty(value = "IT")
  private String domain;

  
...
}