Swagger (OpenAPI)：如何指定从自定义对象动态生成的示例字符串？

Question

上下文

假设你有：

public class Dto {
  private String name;
  private String List<String> customs;

  // getters and setters...
}

和

public class Custom {
  private String something;
  private String else;
  
  // getters and setters...
}

您的 Spring MVC RestController 收到 Dto 的列表：

@PostMapping
public String create(@RequestBody List<Dto> dtos) {
  return myService.process(features);
}

输入

但是，您知道将数据发送到您的控制器的客户端服务将发送如下内容：

[
  {
    "name": "Bob",
    "customs": [
      "{\n        \"something\": \"yes\",\n        \"else\": \"no\"\n      }"
    ]
  }
]

注意String 是Custom 类的 json 表示。请假设这不能在客户端更改，我们必须在服务器端处理它。

问题

是否有一个 OpenAPI 注释允许我将 Custom 指定为自动转换为 String 的对象，然后将其用作 UI 中的示例？

通过“用作示例”，我说的是这个自动生成的 json（请忽略那里显示的实际数据，因为它与提出的简化问题不匹配）：

我要求自动设置，因为如果我们最终修改属性，我宁愿不必回到String 的细节Custom 类（例如，删除 something 属性）。

我们正在使用这些 Maven 依赖项：

    <!-- Swagger / OpenAPI -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>3.0.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>3.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.4.1</version>
    </dependency>

Answer 1

为了将 DTO 指定为要自动转换为 openAPI 文档 UI 的字符串表示的对象，Swagger openApi 提供了一组可在此库中找到的注释：

<groupId>io.springfox</groupId>
<artifactId>swagger-annotations</artifactId>
<version>...</version>

您可以使用它们来解决您的问题，方法是在您的 Dto 上使用 @ApiModel 注释。

通过使用这些注释，您的模型的所有更改都会自动获取并更新到文档中