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（请忽略此处显示的实际数据，因为它与所呈现的简化问题不匹配）：

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

我们正在使用这些 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>

通过在@ApiModel上使用@ApiModel注释，您可以利用它们来解决您的问题。

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