Swagger - "Required @OA\Info() not found"

Question

I just got into api documentation and tried to use Swagger

here is my php file with routes that I want to document:

<?php

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My First API", version="0.1")
 */
return [
    /**
     * @OA\Get(
     *     path="/api/v1/test",
     *     @OA\Response(response="200", description="An example resource")
     * )
     */
    'GET api/v1/test' => 'test/index',
];

But when I run ./vendor/bin/openapi api/config/routes.php cli only outputs errors:

Warning: Required @OA\Info() not found
Warning: Required @OA\PathItem() not found
openapi: 3.0.0

I then tried Swagger2 and it worked just fine

Im using php8.1 from php:8.1-fpm-alpine docker image, the latest zircote/swagger-php package and the Yii2 framework

Answer 1

Turns out openapi was not autoloading classes from my subfolders

The solution is very simple: generate docs from inside of a console application (for example I have a php yii open-api/generate-docs command)

That way composer and yii2 load all of the classes needed for swagger

You also have to anchor all of the attributes to specific classes so the approach in the original question will not work; my solution was to create a compiled router with each route having a separate class with php8.1 attributes