l5-swagger/swagger-php - 将组件添加到块中使其从输出中消失答案

【问题标题】：l5-swagger/swagger-php - adding component to block makes it dissapear from the outputl5-swagger/swagger-php - 将组件添加到块中使其从输出中消失
【发布时间】：2022-07-19 20:19:07
【问题描述】：

如果我将此响应添加到我的定义中：

@OA\Response(
    response="default",
    description="unexpected error",
    @OA\JsonContent(ref="#/components/schemas/ErrorModel"),
    @OA\XmlContent(ref="#/components/schemas/ErrorModel"),
    @OA\MediaType(
        mediaType="text/xml",
        @OA\Schema(ref="#/components/schemas/ErrorModel")
        ),
        @OA\MediaType(
          mediaType="text/html",
          @OA\Schema(ref="#/components/schemas/ErrorModel")
        )
 )

然后我将 Schema 放在下面，如下所示：

/**
 * @OA\Schema(
 *     schema="ErrorModel",
 *     required={"code", "message"},
 *     @OA\Property(
 *         property="code",
 *         type="integer",
 *         format="int32"
 *     ),
 *     @OA\Property(
 *         property="message",
 *         type="string"
 *     )
 * )
 */

命令：php artisan l5-swagger:generate 不会出错，但包含组件响应定义的块不再包含在 json 中，但组件的架构会？

我是否做了一些非常明显的错误，因为到目前为止我在图书馆的经验是，如果你做错了什么，它通常会告诉你。

【问题讨论】：

标签： php swagger laravel-8 swagger-php

【解决方案1】：

如果这是一个新项目的变化是你现在使用的是 swagger-php V4。在版本 4 中，分析器代码使用反射。这样做是为了可以使用注解或 PHP 8 属性。

一个缺点是不再检测独立的文档块，因为没有反射来访问它们。

在您的情况下，我认为拥有两个单独的 /** */ 块将意味着只找到最后一个。

一种解决方法是将类前面的所有注释放在一个 /** */ 块中。另一种选择是为这种情况使用（未使用的）虚拟类。

在这里，添加class ErrorModel {}fater 你的架构也应该可以工作，假设第一个注释有一个单独的响应类。

这同样适用于其他顶级注释，如 @OA\Info 或其他。

【讨论】：

@DemManoMann - 感谢您将它们移动到同一个 /** */ 块中，解决了整个块丢失的问题。

【解决方案2】：

注解不能分开，应该在同一个块中

示例：

改变这个：

/** 
 * @OA\Info( 
 *      version="1.0.0", 
 *      title="Service",
 *      description="Service",
 *      @OA\Contact(
 *          email="contact@email.com"
 *      ),
 *     @OA\License(
 *         name="Name"
 *     ),
 * ),
 */

/**
 * @OA\Schema(
 *     schema="ErrorModel",
 *     required={"code", "message"},
 *     @OA\Property(
 *         property="code",
 *         type="integer",
 *         format="int32"
 *     ),
 *     @OA\Property(
 *         property="message",
 *         type="string"
 *     )
 * )
 */

为此：

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="Service",
 *      description="Service",
 *      @OA\Contact(
 *          email="contact@email.com"
 *      ),
 *     @OA\License(
 *         name="Name"
 *     ),
 * ),
 *
 * @OA\Schema(
 *     schema="ErrorModel",
 *     required={"code", "message"},
 *     @OA\Property(
 *         property="code",
 *         type="integer",
 *         format="int32"
 *     ),
 *     @OA\Property(
 *         property="message",
 *         type="string"
 *     )
 * )
 */

【讨论】：