Swagger - "Required @OA\Info() not found"
When migrating from Swagger Annotations (Swagger2) to OpenAPI 3.0, developers often encounter a specific error during code generation: Warning: Required @OA\Info() not found. This issue frequently appears when using the zircote/swagger-php library with frameworks like Yii2 or Laravel. The error message is explicit about what is missing, but the solution requires understanding how OpenAPI 3.0 differs structurally from its predecessor and how the annotation parser interprets return values in framework routing configurations.
In your specific scenario, the error occurs because you are attempting to define an @OA\Info annotation directly on a PHP array returned by a route definition file. While Swagger2 was relatively lenient with metadata placement, OpenAPI 3.0 is strict regarding the document structure. The parser expects the @OA\Info object to be part of the root-level annotations that describe the entire specification, not merely attached to a specific path or return array in a configuration file.
When you run the command ./vendor/bin/openapi api/config/routes.php, the tool scans the file for annotations. It finds your @OA\Get annotation for /api/v1/test. However, it fails to locate an @OA\Info annotation at the document root level. In OpenAPI 3.0, the info object is mandatory and must be defined globally before any paths are declared. Your current code snippet places the @OA\Info inside a PHP array structure that maps to routes. The parser processes this file expecting a standard OpenAPI document structure where annotations define the global context first.
To resolve this, you need to separate the global metadata from the path-specific definitions or ensure the @OA\Info is applied directly to the main document object, not nested within a route array. If you are using Yii2's routing configuration approach, you must apply the @OA\Info annotation to the file itself or wrap the entire array in a root-level annotation that signifies the start of the OpenAPI document.
Consider restructuring your PHP file to explicitly define the global info block before defining paths. The correct pattern for OpenAPI 3.0 usually looks like this, where the @OA\OpenApi class is instantiated with the required properties:
<?php
use OpenApi\Annotations as OA;
/**
* @OA\OpenApi(
* openapi="3.0.0",
* info=@OA\Info(
* title="My First API",
* version="0.1"
* ),
* components=@OA\Components(), // Optional but good practice
* paths=[
* /**
* * @OA\Get(
* * path="/api/v1/test",
* * @OA\Response(response="200", description="An example resource")
* * )
* */
* 'GET api/v1/test' => 'test/index',
* ]
* )
*/
return [
// Ensure the return value matches what the OpenAPI generator expects.
// Often, returning a raw array of routes is fine for frameworks,
// but the annotations must be attached to the file scope or the root object.
];
The key distinction here is that @OA\Info cannot float freely inside a return array without being anchored to the document root structure expected by the generator. In Swagger2, the parser was often forgiving and could infer the API definition from scattered annotations. OpenAPI 3.0 requires a rigid hierarchy: OpenApi -> Info -> Paths.
If you are using the zircote/swagger-php package with Yii2, ensure that your configuration file is being treated as the primary document source. Sometimes, simply moving the @OA\Info annotation above the return statement and applying it to the entire file scope resolves the parsing logic without needing to change the routing array structure itself.
Another common pitfall involves the order of operations. The generator reads the file top-to-bottom. If you have other annotations that might conflict or if the PHP parser encounters a syntax issue before processing the @OA\Info, it might silently skip the metadata. Ensure there are no syntax errors preceding the info block.
Finally, verify that your command line invocation points to the correct file containing the root-level annotations. If you define routes in api/config/routes.php but place the Swagger annotations in a separate file, the generator will not find them unless you explicitly include or reference that file during generation. Consistency in where the @OA\Info resides relative to the path definitions is the single most important factor for OpenAPI 3.0 compliance.