英文:

Swagger (OpenAPI) : how to specify example String dynamically generated from a custom Object?

问题

# Context

假设您有：

```java
public class Dto {
  private String name;
  private 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);
}

Input

但是，您知道客户端服务将向您的控制器发送类似于以下内容的数据：

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

请注意**“String”是“Custom”类的 JSON 表示**。请假设在客户端无法更改此内容，我们必须在服务器端处理它。

Question

是否有一个 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>

<details>
<summary>英文:</summary>

# Context

Say you have:

    public class Dto {
      private String name;
      private String List&lt;String&gt; customs;
    
      // getters and setters...
    }

and

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

Your Spring MVC ``RestController`` receives a list of ``Dto``:

    @PostMapping
    public String create(@RequestBody List&lt;Dto&gt; dtos) {
      return myService.process(features);
    }

# Input

However, you know that the client-side service which will send data to your controller will send something like this:

    [
      {
        &quot;name&quot;: &quot;Bob&quot;,
        &quot;customs&quot;: [
          &quot;{\n        \&quot;something\&quot;: \&quot;yes\&quot;,\n        \&quot;else\&quot;: \&quot;no\&quot;\n      }&quot;
        ]
      }
    ]

Notice how **the ``String`` is a json representation of the ``Custom`` class**. Please assume this cannot be changed on the client-side and we have to deal with it on the server-side.

# Question

Is there an OpenAPI annotation which would allow me to designate ``Custom`` as being the object to be automagically converted to a ``String`` which would then be used as the example in the UI?

By &quot;used as the example&quot;, I&#39;m talking about this automatically generated json (please disregard the actual data shown there since it doesn&#39;t match the presented simplified problem):

[![Swagger UI screenshot to better illustrate][1]][1]

I&#39;m asking for an ***automatic*** set up because I would prefer not having to go back onto the ``String``&#39;s specifics if we end up modifying the properties of the ``Custom`` class (removing the ``something`` attribute, for example).

We are using those Maven dependencies:

		&lt;!-- Swagger / OpenAPI --&gt;
		&lt;dependency&gt;
			&lt;groupId&gt;io.springfox&lt;/groupId&gt;
			&lt;artifactId&gt;springfox-swagger2&lt;/artifactId&gt;
			&lt;version&gt;3.0.0&lt;/version&gt;
		&lt;/dependency&gt;
		&lt;dependency&gt;
			&lt;groupId&gt;io.springfox&lt;/groupId&gt;
			&lt;artifactId&gt;springfox-swagger-ui&lt;/artifactId&gt;
			&lt;version&gt;3.0.0&lt;/version&gt;
		&lt;/dependency&gt;
		&lt;dependency&gt;
			&lt;groupId&gt;org.springdoc&lt;/groupId&gt;
			&lt;artifactId&gt;springdoc-openapi-ui&lt;/artifactId&gt;
			&lt;version&gt;1.4.1&lt;/version&gt;
		&lt;/dependency&gt;


  [1]: https://i.stack.imgur.com/HIjb4.png

</details>


# 答案1
**得分**: 1

为了将DTO指定为自动转换为字符串表示以供openAPI文档UI使用，Swagger openApi提供了一组在这个库中找到的注释：

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

您可以利用这些注释来解决您的问题，通过在您的DTO上使用[`@ApiModel`][1]注释。

通过使用这些注释，所有对模型的更改都会被捕捉到，并自动更新在文档中。


[1]: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations

<details>
<summary>英文:</summary>

In order to designate DTO as being the object to be automatically converted to a string representation for the openAPI documentation UI, Swagger openApi provides a set of annotations found in this library:

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

You can make use of them to fix your problem, by using the [`@ApiModel`][1] annotation on your Dto. 

By using these annotations all changes to your models are picked up and updated in the documentation automatically


  [1]: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations

</details>