java - 如何在 OpenApi Spring 上添加不同的 @Schema 描述？

Question

我在使用 OpenApi 和 Spring 定义我的 API 时遇到了一些问题。我正在使用此依赖项：

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-ui</artifactId>
   <version>1.5.2</version>
</dependency>

我的问题是我想在不同的 Api 响应上定义一个 @Schema，但在每个响应中使用不同的描述和示例。

现在我有一个看起来像这样的响应：

public class LoginResponse {

    @Schema(description = "User identifier", example = "12")
    private Long id;
    @Schema(description = "User balance", example = "{"type":"COINS","amount":1000}")
    private Balance balance;
...

和其他看起来像这样的回应......

public class ModifyBalanceResponse {

    @Schema(description = "User identifier", example = "12")
    private Long id;
    @Schema(description = "Added balance", example = "{"type":"COINS","amount":500}")
    private Balance addedBalance;
    @Schema(description = "Updated balance", example = "{"type":"COINS","amount":1500}")
    private Balance updatedBalance;
...

因此，我拥有具有三个不同描述和示例的对象“Balance”，但是当它生成文档时，使用该对象的所有响应和字段都采用相同的描述和示例。

我已经看到，在生成的文件中，我将所有带有“$ref”标签的项目都添加到 Balance 模式，并且仅使用定义的描述/示例之一生成，如下所示：

addedBalance:
   $ref: '#components/schemas/Balance'

我试图手动编辑文件，我可以通过将其替换为...来查看我想要的 swagger doc

addedBalance:
   title: Balance
   description: Added balance
   example: '{"type":"COINS","amount":500}'

有什么办法可以用openapi提供的Spring注解来做这样的事情吗？诸如忽略模式对象并从字面上理解描述和示例之类的事情。我不介意它是否没有引用模式对象。

感谢优势。

标签： javaspringswaggeropenapi