Can't generate API documentation in l5-swagger - php

Question

I'm starting to study swagger.
I'm trying to do the same which is done in a book "Hands-On Full Stack Web Development with Angular 6 and Laravel 5".
Using php-fpm bash after typing command "php artisan l5-swagger:generate"
I have got this exception in VS Code terminal:
root#8e6435be9103:/application# php artisan l5-swagger:generate
Regenerating docs
ErrorException : Required #OA\Info() not found
at /application/vendor/zircote/swagger-php/src/Logger.php:39
35| $this->log = function ($entry, $type) {
36| if ($entry instanceof Exception) {
37| $entry = $entry->getMessage();
> 39| trigger_error($entry, $type);
40| };
41| }
42|
43| /**
Exception trace:
1 trigger_error("Required #OA\Info() not found")
/application/vendor/zircote/swagger-php/src/Logger.php:39
2 OpenApi\Logger::OpenApi\{closure}("Required #OA\Info() not found")
/application/vendor/zircote/swagger-php/src/Logger.php:71
And when I trying to open http://localhost:8081/api/documentation url it gives this error:
Failed to load API definition.
Fetch errorNot Found http://localhost:8081/docs/api-docs.json
I'am using php-fpm bash inside docker.
My OS is Ubuntu 18.04.3 LTS.
Can anyone help me to fix this problem.
Thank you!!!

Answer 1

You have to put some annotations in your code before running php artisan l5-swagger:generate. First, go to app/Http/Controllers/Controller.php and add a phpdoc comment block as follow before the class declaration:
/**
* #OA\Info(title="My First API", version="0.1")
*/
This annotation by itself is sufficient to resolve the issue that you described, but if you execute php artisan l5-swagger:generate again you will see the following Exception:
ErrorException : Required #OA\PathItem() not found
at /home/nathanael/dev/laravel-projects/laravel-swagger/vendor/zircote/swagger-php/src/Logger.php:39
35| $this->log = function ($entry, $type) {
36| if ($entry instanceof Exception) {
37| $entry = $entry->getMessage();
38| }
> 39| trigger_error($entry, $type);
40| };
41| }
42|
43| /**
Exception trace:
1 trigger_error("Required #OA\PathItem() not found")
/home/nathanael/dev/laravel-projects/laravel-swagger/vendor/zircote/swagger-php/src/Logger.php:39
2 OpenApi\Logger::OpenApi\{closure}("Required #OA\PathItem() not found")
/home/nathanael/dev/laravel-projects/laravel-swagger/vendor/zircote/swagger-php/src/Logger.php:71
Please use the argument -v to see more details.
That's because you must have at least one method in a controller with an annotation that describes a route.
You can easily create a resource in your application to test running php artisan make:controller ProjectsController -r and adding Route::resource('projects', 'ProjectsController') to routes/web.php.
After creating the controller open it and add the following phpdoc comment block before the index method, for example:
/**
* #OA\Get(
* path="/projects",
* #OA\Response(response="200", description="Display a listing of projects.")
* )
*/
Then, run php artisan l5-swagger:generate again and you must see a success message in the terminal.