如何在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”标签来平衡模式，并且这是仅使用定义的描述/示例之一生成的，如下所示：

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

我尝试手动编辑该文件，并且通过将其替换为...，我可以根据需要查看 swagger 文档。

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

有没有办法用openapi提供的Spring注解来做这样的事情？ 比如忽略模式对象并按字面意思理解描述和示例。我不介意它是否没有引用架构对象。

感谢您的优势。

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 {}

一定有更好的解决方案...