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

根据迁移文档，您需要导入注释类

use OpenApi\Annotations as OA;

这将解决您的问题。

Answer 3

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

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

Answer 4

我在迁移到

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

如果您不想一次性迁移很多注释，则可以使用这两种类型的注释。