Generate a swagger documentation in laravel without PHPDoc or comment ? It’s possible

4 min readJun 1, 2021

A tutorial on how to get a Laravel API swagger documented with https://github.com/Mezatsong/laravel-swagger-docs

Laravel is a great php framework, with a lot of tools to facilitate the development of applications in PHP. However, despite all its qualities, it has the drawback of not having its own system for documenting APIs.

Usually laravel backend developers use external tools to document their API and this is a task that most hate doing.

In the vast majority of cases, developers will write the documentation themselves, whether through comments on functions or even outside the code, even if a minimum of comments is inevitable (eg: a simple string for description) to have a good documentation, there is usually too much to write besides the code to have a ready-made documentation and moreover you have to do maintenance on each change because it is not synchronized with the code.

In this article, I offer a half solution to this problem, using a package that will generate most of the documentation for us. We will not have to document our models, nor our requests. Due to the flexibility of the response types in the php functions, we will still have to document our responses.

Setup

Let’s start by creating new laravel application project using composer.

composer create-project --prefer-dist laravel/laravel my-api

In this tutorial I’ll assume you have a basic understanding of editing your hosts file, make sure to set APP_URL correctly because the package will use it, so we’ll serve our application straight on localhost for time’s sake.

cd my-api && php artisan my-api

CTRL+C to stop the server.

Laravel Swagger Docs

Laravel-swagger-docs is the package that we need in our projects to generate documentation.Installation

Install package

composer require mezatsong/laravel-swagger-docs

Publish configuration files and views

php artisan vendor:publish --provider "Mezatsong\SwaggerDocs\SwaggerServiceProvider"

Edit the swagger.php configuration to enable swagger, or by setting SWAGGER_ENABLE env variable to true, you can also setup many others thing, read this settings file to see all you can configure in it.

Usage

Laravel Swagger Docs works based on recommended practices by Laravel. It will parse your routes and generate a path object for each one. If you inject Form Request classes in your controller’s actions as request validation, it will also generate the parameters for each request that has them. For the parameters, it will take into account wether the request is a GET/HEAD/DELETE or a POST/PUT/PATCH request and make its best guess as to the type of parameter object it should generate. It will also generate the path parameters if your route contains them. The models documentation will also be generated by inspecting each model table schema.

Let’s create a post model with migration for an illustrion

php artisan make:model Post --migration
php artisan migrate

Now let edit post migration and add colums with comment if you want to add description in your models

After, we will add something in users migration

After that, let’s create controllers, requests, and routes, for that, run the followings commands:

php artisan make:controller PostController
php artisan make:request Post/CreatePostRequest
php artisan make:request Post/UpdatePostRequestphp artisan make:request User/UpdateUserRequest
php artisan make:controller UserController

Now let’s write the code needed

Before continue, let’s explan the Response directive, we have a code which is the http response code, you can describe the response and finally we have ref with is a reference to your model, you also put the model name inside [] to refer array of that model, or insideP() to refer a pagination response or even create your own.

The summary is extracted from the first comment line and after that, we skip a line to start with the operation description.

Now I would like to show you how to package can handle even model relationships, to do so, just fill the$with model property for laravel eager loading, as an example, we have user_id column in our posts table:

At this point we have almost do everthing needed, now you can generate the swagger doc if you did not enable it by tapping this command:

php artisan swagger:generate

And we get result:

As with most tutorials, what I have presented in this article is not complete. I have not covered everything that can be done with the package. I recommend you visit the package on Github to get a better understanding on how everything works and the syntax involved in more complex requests. You can get the complete repository of this tutorial at https://github.com/Mezatsong/laravel-swagger-docs-example

Thanks for reading!