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

【问题标题】：Documenting multiple response possibilities with OpenApi annotation使用 OpenApi 注释记录多种响应可能性
【发布时间】：2021-09-27 01:03:28
【问题描述】：

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

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

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

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

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

<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 文件，这不是我所需要的。

【问题讨论】：

标签： swagger openapi swagger-php

【解决方案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")
            )
        }
    )
)

【讨论】：