如何在OpenApi Spring上添加不同的@模式描述？

Question

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

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

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

现在我有一个这样的回答：

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'

我试图手动编辑该文件，通过将其替换为。。。

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

有没有办法用openapi提供的Spring注释来做这样的事情？有点像忽略schema对象，从字面上理解描述和示例。我不介意它是否引用到schema对象。

感谢您的惠顾。

Answer 1

您还可以在类中使用泛型来强制SpringDoc将其视为不同的类型。

public static class Balance<T> {
   ...
}

public static class ModifyBalanceResponse {

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

public static class Added {}
public static class Updated {}

Answer 2

这很蹩脚，但您可以通过为每个项目创建不同的响应类来解决这个问题。

public class AddedBalance extends Balance {}
public class UpdatedBalance extends Balance {}

一定有更好的解决办法...