Do you work on the documentation for your API in the application? I hear a faint yes! I understand it’s one of the areas which every developer despises. But here’s the thing- documentation is the core part of any application.
It helps you understand what an application does without jumping into the whole application. Without any documentation, even a small project is hard to understand by peers and co-workers. They will find difficult to find the API endpoints and usages.
Swagger is the most popular and real-time authorization framework of API developer tool. Swagger allows real-time authorization and endpoint testing for testers and developers without any extra efforts. Swagger is launched and maintained by SmartBear.
This tutorial will guide you on how you can integrate swagger with Laravel project in a few steps. So let’s start integrating swagger in our application-
- Let’s create our new Laravel application using the following mentioned command.
2. Install the composer using the command mentioned below.
3. Swagger requires the hostname of our application, so in this tutorial, we will be using hostname as localhost. You need to run the following commands to create a development folder and corresponding swagger scripts.
4. We need to edit the swagger.sh to generate the documentation. Let’s add the script in the file. This file also has the path where we will show the output JSON.
5. Now we need to add the following lines inside our swagger-constants.php file.
6. Edit the last file that we created in Laravel scripts i.e swagger-v1.php
7. Run the scripts file swagger.sh using the following command.
8. You should see the output as mentioned below.
Hurray! But wait, we still need to do some more setup to finally test our application’s endpoints.
9. Create a custom controller called GetComponentDetailController inside the (app/Http/Controllers/GetComponentDetailController.php) and endpoints to access this controller inside our route file.
10. Our GetComponentSectionInfo controller will look like this-
11. We can now test this endpoint on our browser like this-
If you followed all the steps correctly, you will see the output as below-
12. Till now we have our documentation ready with the respected output but we need to add user interface so that we can test our application’s endpoints. When we run our swagger.sh file, it generates a subfolder inside a public folder with a file named as swagger.json which contains the information about endpoints and required data.
13. For the user interface download the entire folder from this GitHub link and place it inside the swagger folder. Now, we need to edit the paths in the downloaded files. Let’s first update the index.html which is placed in dist folder. For the reference, you can copy and paste directly from the below-
14. To generate documentation in the swagger.json file, let’s add the swagger annotation above the getData method and run./swagger.sh file to generate the JSON in the swagger.json file.
15. Now try this link to open swagger UI. You should see something like this.
16. Click on any route endpoint, there will be an input field for component name and component description as shown above. Enter the value and execute the GET request. You will see the output like this.
You can check this link for more swagger documentation.
Hope you find this useful. For any help, please drop in your comments.