L5-swagger api 文档：获取错误必需的 @OA\PathItem() 未找到

Question

阅读 Stackoverflow 上的这两篇文章后： ​​如何解决 ErrorException：未找到必需的 @OA\PathItem() 无法在 l5-swagger 中生成 API 文档

运行 php artisan l5-swagger:generate 后，我仍然收到错误Required @OA\PathItem() not found。

这是我的 Controller.php 部分：

/**
 * @OA\Info(
 *     title="My First API Documentation",
 *     version="0.1",
 *      @OA\Contact(
 *          email="[email protected]"
 *      ),
 * ),
 *  @OA\Server(
 *      description="Learning env",
 *      url="https://foo.localhost:8000/api/"
 *  ),
 */
class Controller extends BaseController
{

这是我的 ProfileController 部分：

   /**
     * @OA\Get(
     *      path="/profiles",
     *      @OA\Response(
     *          response=200,
     *          description="Successful operation",
     *      ),
     *     @OA\PathItem (
     *     ),
     * )
     */
   function index()
    {
        return new ProfileCollection(Profile::with('user')->paginate());
    }

我在这里忽略了什么？ 如果有人可以解释和提供帮助，那就太好了:)

编辑 - 解决方案

出现问题是因为我使用的是 laravel 模块包，并且我必须更改 l5-swagger.php 配置中的一些代码文件：

'annotations' => [
                    base_path('Modules/Api/Http'), <-- changed the base path to the correct module
                ],

然后，我将主 Controller.php 从 App/Http/Controllers 复制到同一模块，以消除之后出现的 @OA\Info() not found 错误。

Answer 1

当我第一次安装和配置时，我遇到了同样的错误。事实证明，仅 @OA\Info 不足以生成文档。除此之外，它还需要至少一个路径条目。添加 api 端点注释后，它得到修复。

例子：

/**
 * @OA\Get(
 *     path="/api/users",
 *     @OA\Response(response="200", description="An example endpoint")
 * )
 */
 public function getUsers() {
    ...
 }

Answer 2

我在迁移到 v4.8.x 时遇到了这个问题，此时 doctrine/annotations 作为依赖项被删除。

您需要添加 doctrine/annotations 作为依赖项，或者更改为使用 PHP 注释，即，

use OpenApi\Attributes as OA;

#[OA\Info(
    version: '1.0.0',
    title: 'My API'
)]

如果

/**
 * @OA\Info(
 *   version="1.0.0",
 *   title="My API"
 * )
 */

您不想一次全部迁移，则可以使用两种类型的注释。

命令：

composer require doctrine/annotations

Answer 3

根据迁移文档您需要导入 Annotations 类 use OpenApi\Annotations as OA; 这将解决您的问题。

Answer 4

/**
 * Remove the specified resource from storage.
 *
 * @return \Illuminate\Http\JsonResponse
 */

如果我的index()函数上面有这些代码，应该立即删除它。这就是我收到此错误的原因

Answer 5

当在 Laravel 中使用 OpenAPI 注解（例如 @OA\PathItem()）而未安装必要的包时，通常会发生此错误。确保您已正确安装 darkaonline/l5-swagger 包，因为它在 Laravel 中提供对 OpenAPI 注释的支持。

如果您已经安装了该软件包，请确保您已正确遵循所有设置步骤，并且正确定义了路由和注释。如果问题仍然存在，您可能需要检查代码和配置以识别任何缺失或配置错误的元素。