Achieving a Well-Documented Solution and Use of the Swagger Tool in Laravel

26 Jan, 2021 | 4 minutes read

We live in a modern era where software quality is crucial for success. Some software solutions are developed in months, some in years,  which usually is followed by a change in the development teams. Code quality, defined code standards, and good documentation can only lead as to how we do and how we must set our project architecture now and in the future. In this blog post, we are going to discuss the documentation part, the swagger tool, and how it helps us to organize our projects better and know what we are doing.

Documentation

So, let’s answer one big question What tools did we use in our latest project to achieve a well-documented solution?

  • Our time is planned, we have defined sprints and assigned tasks and every task is explained in a story to make it more understandable. So, with the JIRA system, we can follow the history of a project to write better documentation.
  • We use version control GIT to follow the code versions, but with the GitLab, the platform is more than that. We have defined rules on how to use version control so when you look at the history you know when something is developed or fixed. Quality code and Code review are also part of our development.   
  • Because we use an API-based solution we use the swagger tool to document our API which will be ready to be connected to any app in the feature (SPA or Mobile). (More about swagger later).
  • Our project repository contains README.md – We document here things that are on the Laravel developer level (where to find something, how to use it,  installations, releases, hints, keywords, etc). In short, this is the documentation for current and new members of the team.
  • Client documentation and architecture documentation are updated also.

We say that we develop a lot but we document also in parallel.

What is Swagger?

By definition, Swagger is an Interface Description Language for describing RESTful APIs expressed using JSON and this is pretty much an abstract answer. But let’s explain it like a story.

Imagine you are a front-end developer in our team and you need to build the client-side for our e-commerce shop that is using the API. You read the general documentation but now you need to connect and try to ping some of the endpoints. You don’t know the parameters, or defined headers, so what do you need? You need the API documentation URL where SWAGGER lives and you can begin to ping the API endpoints over the web interface. And that’s all.

Why do we use Swagger?

The first reason why to use SWAGGER documentation is that it is easily accessible and can be updated whenever you want. We can say that SWAGGER follows a nice pattern that helps you to document your API smart. SWAGGER is a must-have and looking from the back-end perspective saves a lot of pain and time when we need to know what’s done, what’s an issue, and how it works.

Project setup and Swagger package

PHP is driven by a huge community and there are several SWAGGER packages that can be integrated with any PHP code or web framework.

This SWAGGER package (DarkaOnLine) contains 2 parts:

  • “The annotation compiler and swagger generator” – Annotation syntax that is defined over every endpoint method in the class which later is compiled to generate swagger syntax code.
  • “The UI part” – where generated swagger syntax code is put in nice UI and can be accessed through URL like <api_user>/api/documentation.

We must say that the DarkaOnLine package is totally flexible. You can overwrite the default config easily. In addition, you can: 

  • change the UI part URL
  • Hide the document for projects that are ready for production, etc.

Now, let’s jump to the integration part.

Integration

We use Laravel 8 (currently the latest version) so through Composer (package manager for PHP) we can install DarkaOnLine.

1composer require "darkaonline/l5-swagger"

When the package is installed, we need to open AppServiceProvider (located in app/Providers) and add this line in the register method.

1$this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);

or we can open config/app.php and add this line in the provider’s section

1L5Swagger\L5SwaggerServiceProvider::class,

to overwrite the default configs we need to run:

1php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

This will generate the config in config/l5-swagger.php.

You’re done. Now you can write SWAGGER annotations and manually compile with:

1php artisan l5-swagger:generate

Swagger real-time

So here we share with you a short video where we will demonstrate how we use the SWAGGER tool and how we document our project.

If you want to find out more about using the Swagger tool and documenting projects, feel free to contact us.

Conclusion

All in all, we can say that seeing documented code is awesome and for documenting APIs, swagger is a nice tool to have. We will definitely continue in this way now and in the future. If you like it, do let us know.

Happy coding!

Author :

Andrej Nankov