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

Question

我想要一种方法来声明一些对每个端点都相同的响应；例如，如果您没有正确的令牌，每个端点都将输出 401，然后如果您没有有效的 [=，则可以有另一组端点将全部输出 404 14=] 在你的道路的开始。

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

* @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"，none 其中可以用作标识符。

我将其与 L5-swagger 结合使用以获得 Laravel 支持。

Answer 1

在操作之外声明响应：

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

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

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

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

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

Are declarations of entire responses reusable in swagger-php?

annotations

swagger

swagger-php

openapi