OpenApi 為請求正文添加示例

Question

Am working with Spring boot and I am using springdoc-openapi-ui to generate spec files using swagger editor The issue Is, Am trying to avoid creating model classes just to use them in the request body to show them with 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;

然后我可以使用我剛剛創建的 model class，如下所示。

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

問題

• 是否可以僅為此目的做 model class ？
• 有沒有辦法添加一個示例，以便 UI 團隊了解如何使用它。
• 我知道 model class 可以幫助生成 UI 客戶端（例如 JSClient ），但這真的有必要嗎？ 我的意思是我們不能克服這個問題嗎？

任何答案、建議、鏈接表示贊賞， swagger 文檔對我的情況沒有幫助。

Answer 1

我的兩分錢：

是否可以僅為此目的做 model class ？

是的，您應該為您的@RequestBody 使用 model class 因為每個端點都必須有一個合同來傳達需要使用的有效負載。 添加注釋是一個很好的做法

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

有沒有辦法添加一個示例，以便 UI 團隊了解如何使用它。

不，Swagger 將 map 一個 POJO class 與 @Schema 等裝飾器。 ObjectNode 沒有有效的用例表示

我知道 model class 可以幫助生成 UI 客戶端（例如 JSClient ），但這真的有必要嗎？ 我的意思是我們不能克服這個問題嗎？

好吧，根據我的經驗，使用 Swagger 工具的好處多於壞處。 有必要注意相關的約束嗎？ 我認同