annotations - 整个响应的声明是否可以在 swagger-php 中重用？

Question

我希望有一种方法来声明一些对每个端点都相同的响应；例如，如果您没有正确的 token ，每个端点都将输出 401，如果您没有，则可以有另一组端点将全部输出 404在路径的开头没有有效的 id。

所以对于几乎​​每一种方法，我都发现自己在复制粘贴这样的东西:

* @OA\Response(response=401, description="If no token..."),
* @OA\Response(response=404, description="If ID of thing invalid..."),

getting started section表示支持可重用响应，但仅涵盖(成功响应的)属性。

没有关于我正在寻找的那种东西的例子，而且我也无法让自己猜测任何可以编译的东西。

像 @OA\Response(ref="#/components/schemas/Unauthorized") 似乎应该是这样的(并且编译不会提示 ref 属性)，但是我如何声明 Unauthorized 架构是什么样的？因为声明 @OA\Response 表示它只需要以下字段:"ref"、"response"、"description"、"headers"、"content"、"links"、"x "，这些都不能作为标识符。

我将它与 L5-swagger 结合使用以支持 Laravel。

Answer 1

在操作之外声明响应:

/**
 * @OA\Response(response="Unauthorized", description="If no token...")
 */

这会将其添加到 #/components/responses/ 中，使用 response= 作为键值。

然后您可以稍后在操作中重用它:

/**
 * @OA\Get(
 *   path="/example",
 *   @OA\Response(response=401, ref="#/components/responses/Unauthorized")
 * )
 */