Can't generate API documentation in l5-swagger
When attempting to regenerate L5 Swagger documentation, encountering an ErrorException stating "Required @OA\Info() not found" usually points to a fundamental configuration issue rather than a runtime bug. This specific error originates from the zircote/swagger-php library, which acts as the engine behind the package. The logger within this library triggers the exception because it cannot find a root annotation block in your codebase that defines the basic metadata for your API.
In Swagger/OpenAPI terms, every valid specification document must start with an info object. This object contains mandatory fields like the title and version number of your API. Without this root anchor, the scanner has no context to begin building the document structure. The error trace you are seeing confirms that the code generator scanned your application but failed to encounter a single line of code declaring this required information.
To resolve this, you must ensure your src/annotations.php file (or whichever file you configured in composer.json) contains a valid root annotation. If you are following older tutorials, such as those found in "Hands-On Full Stack Web Development with Angular 6 and Laravel 5," you might be using outdated boilerplate code that assumes a specific structure no longer exists by default in modern L5 Swagger setups.
The solution involves updating your src/annotations.php to explicitly define the API metadata. You should wrap your route groups or controller imports inside an @OA\Info() block. Here is a minimal, functional example of what that file should look like:
<?php declare(strict_types=1);
use OpenApi\Annotations as OA;
/**
* @OA\Info(
* title="L5 Swagger Petstore",
* version="1.0.0"
* )
*/
return [
// Your existing route groups or controller annotations go here
];
This block provides the mandatory title and version attributes required by the OpenAPI specification. Without these, the generator throws the exception you observed. You can add more optional fields like description or contact details, but the title and version are non-negotiable for the generation process to succeed.
After modifying this file, run the regeneration command again:
php artisan l5-swagger:generate
If the command completes without errors, you can access the documentation at your configured URL, typically http://localhost:8081/api/documentation. However, if the browser still displays a "Failed to load API definition" error or a 404 Not Found status for the JSON endpoint, the issue likely lies in how your Docker container exposes the generated files.
L5 Swagger generates static HTML and JSON files into the public/docs directory (or a similar path defined in your configuration). In a Docker environment running PHP-FPM, you must ensure that this directory is mounted correctly and accessible via the web server serving your application. If your Nginx or Apache configuration inside the container does not serve the contents of the docs folder, the browser will return a 404 even if the generation step succeeded.
Additionally, check your composer.json to ensure the l5-swagger package is correctly mapped. Older versions of this package required specific entries in extra.l5-swagger.openapi-generator, but modern installations often handle this automatically. If you are using a custom route group, ensure that the path defined in the @OA\Info() matches or is compatible with where you intend to serve the docs.
For developers maintaining legacy projects based on older books or tutorials, it is often safer to upgrade the L5 Swagger package to its latest stable version. Older versions had stricter requirements and different default paths that might conflict with current Docker configurations. Ensure your composer.json reflects a compatible version:
"require": {
"l5-swagger/l5-swagger": "^8.10" // Or the latest stable version
},
"extra": {
"laravel": {
"dont-discover": []
}
}
Once the annotations are corrected and the Docker serving configuration is verified, the documentation should generate and load correctly. If you require further assistance with specific custom configurations or complex routing setups, you might find community support or official documentation helpful. For deeper integration questions, resources like https://laravelcompany.com can offer insights into modern Laravel ecosystem tools.