OpenApi为请求正文添加示例

Question

我正在使用Spring引导，我正在使用springdoc openapi ui使用swagger编辑器生成规范文件问题是，我试图避免创建模型类，只是为了在请求体中使用它们来显示招摇的UI。例如：

@RequestMapping(value = "/update/project/{id}", method = RequestMethod.POST,
produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<String> projectUpdate(@RequestBody ObjectNode json, @PathVariable int id)  
{ ... } 

如果我这样使用它，Swagger UI页面上的示例将为空。因此，作为一种解决方案，我必须像下面的一样进行

public class CustomerCreateRequest {

@JsonProperty
private String ProjectId;
@JsonProperty
private String ProjectName;
@JsonProperty
private String ProjectDescription;
@JsonProperty
private String CustomerId;
@JsonProperty
private String CustomerName;
@JsonProperty
private String CustomerDescription;
@JsonProperty
private String BucketId;
@JsonProperty
private String API_KEY;
@JsonProperty
private String Name;
@JsonProperty
private String RedmineId;

然后我可以使用我刚刚创建的模型类，如下所示。

@PostMapping(value = "/createUser")
public ResponseEntity createCustomer(@RequestBody CustomerCreateRequest requestBody)
{ ... } 

问题

• 仅为此目的创建模型类可以吗
• 有没有办法添加一个示例，让UI团队知道如何使用它
• 我知道模型类可以帮助为UI生成客户端(比如JSClient(，但它真的有必要吗？我的意思是，我们不能克服这个问题吗

感谢任何答案、建议、链接，swagger文档对我的情况没有帮助。

Answer 1

我的两分钱：

仅仅为此目的创建模型类可以吗？

是的，您应该为@RequestBody使用一个模型类，因为每个端点都必须有一个协议来传达需要消耗的有效负载。添加像这样的注释是一种很好的做法

@Parameter(description="Some description", example="{"foo":"bar"}")
@RequestBody CustomerCreateRequest requestBody

有没有办法添加一个例子，让UI团队知道如何使用它。

否，Swagger将使用装饰符(如@Schema和其他(映射POJO类。ObjectNode没有用例的有效表示形式

我知道模型类可以帮助为UI生成客户端(如JSClient(，但它真的有必要吗？我的意思是，我们不能克服这个问题吗？

根据我的经验，使用Swagger这样的工具好处大于坏处。有必要关心相关的约束吗？我想是的