l5-swagger/swagger-php -添加阻止组件使其脱离输出。

Question

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

@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")
        )
 )

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

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

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

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

Answer 1

如果这是一个新的项目，那么您现在使用的是swagger-php V4。在第4版中，分析器代码使用反射。这样做是为了能够使用注释或PHP 8属性。

缺点之一是不再检测到独立的文档块，因为没有任何反射来访问这些文档块。

在您的例子中，我认为有两个独立的/** */块意味着只找到最后一个块。

一种方法是在单个/** */块中的类前面有所有注释。另一种选择是在这种情况下拥有(未使用的)虚拟类。

在这里，如果为第一个注释添加了一个单独的class ErrorModel {}类，那么您的模式应该也能工作。

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

Answer 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"
 *     )
 * )
 */