使用 OpenApi 注释记录多种响应可能性

Question

根据传入的参数，我有一个可以返回单个项目或项目列表的endpoint(目前endpoint没有灵活性，我无法更改代码)。

我试图生成API留档与OpenApi注释。

我的endpoint：{{url}}/资格/{qualification_id}/持有者/{holder_id}

{qualification_id}参数是可选的。如果只提供了{}参数，则返回已获得资格的人员列表，例如：

{{url}}/资格/156/持有人返回

<holder>
    <holder>
        <id>34</id>
        <name>Tim</name>
        <expired>false</expired>
    </holder>
    <holder>
        <id>87</id>
        <name>Andy</name>
        <expired>false</expired>
    </holder>
    <holder>
        <id>346</id>
        <name>Ralph</name>
        <expired>true</expired>
    </holder>
<holder>

为此，我的响应注释是：

@OA\Response(
    response=200,
    @OA\JsonContent(
        type="array",
        @OA/Items(ref="#/components/schemas/QualificationHolder")
    )
)

但是，如果还提供了{holder_id}参数，则仅返回特定的资格记录持有人，例如：

{{url}}/qualification/156/holder/346返回：

<holder>
    <id>346</id>
    <name>Ralph</name>
    <expired>true</expired>
</holder>

对此，我的回答是:

@OA\Response(
    response=200,
    @OA\JsonContent(ref="#/components/schemas/QualificationHolder")
)

我的问题是我不知道如何组合这些，以便使用OpenApi注释生成的留档表明响应可以是这些选项中的任何一个，我也找不到任何在线留档来指示任何东西。我找到的一切都指向如何设置json/yaml文件，这不是我需要的。

Answer 1

在深入研究了< code>zircote/swagger-php代码并在查看示例时做了一些假设之后，我通过使用以下注释让它工作了:

@OA\Response(
    response=200,
    @OA\JsonContent(
        oneOf={
            @OA\Schema(ref="#/components/schemas/QualificationHolder"),
            @OA\Schema(
                type="array",
                @OA\Items(ref="#/components/schemas/QualificationHolder")
            )
        }
    )
)