Can't generate API documentation in l5-swagger Can't generate API documentation in l5-swagger
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!!!
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.