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

编程问答 2022-07-21

问题描述

上下文

说你有

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

Swagger UI screenshot to better illustrate

我要求设置 自动 ，因为如果我们最终进行修改，我希望不必回到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>

解决方法

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

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

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

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

javajavaopenapispringspringdocswagger