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

Question

我有一个端点可以 return 单个项目或项目列表，具体取决于传入的参数（目前端点没有灵活性，我无法更改代码）。

我正在尝试使用 OpenApi 注释生成 API 文档。

我的终点：{{url}}/qualification/{qualification_id}/holder/{holder_id}

{holder} 参数是可选的。如果仅提供 {qualification_id } 参数，则获得资格的人员列表是 returned，例如：

{{url}}/qualification/156/holder returns

<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} 参数，则只有那个特定的资格记录持有者被 return 编辑，例如：

{{url}}/qualification/156/holder/346 returns:

<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

在查看示例的同时对 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")
            )
        }
    )
)

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

Documenting multiple response possibilities with OpenApi annotation

swagger

openapi

swagger-php