Can‘t generate API documentation in l5-swagger

Question

I‘m starting to study swagger. I‘m trying to do the same which is done in 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 @OAInfo() 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 @OAInfo() not found")
    /application/vendor/zircote/swagger-php/src/Logger.php:39

2   OpenApiLogger::OpenApi{closure}("Required @OAInfo() 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:

/**
 * @OAInfo(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 @OAPathItem() 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 @OAPathItem() not found")
      /home/nathanael/dev/laravel-projects/laravel-swagger/vendor/zircote/swagger-php/src/Logger.php:39

  2   OpenApiLogger::OpenApi{closure}("Required @OAPathItem() 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:

/**
 * @OAGet(
 *     path="/projects",
 *     @OAResponse(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.