laravel 5: create professional api with automatic api-docs and rest clients with swagger

Prerequisits

We need some things installed on the local machine.

• laravel 5.3 installed
• https://laravel.com/docs/5.3/installation
• node.js installed

An Api is nothing without a good documention. Without Api-docs every consumer stands infront of a black box. Its is very hard to discover the api methods and to find out how all works. Even if the api is well coded an the developers know hoow to use it. I will always need support and training to give your api consumers / partners an idea how to manage your api.

This is where swagger and swagger-ui comes into the game.

Swagger is an defacto industry standard to unifiy Rest Apis over the internet. Swagger defines Standard metadatina for  each of your Api methods in JSON format.
No worry, you dont have to write JSON to get it on. You will "only" have to annotate your Api Classes and its methods.

Swagger UI generates a very useful UI for your REST-API by parsing the swagger.json definition

As you can see, this is a User API with 2 Methods in it. 1 User/list and 1 User/get method.

Swagger UI takes the swagger.json output and turns it inti this nice HTML Pages.

On the top of each Item you can display more information or even a REST Client like that:

Generate REST Clients out of the box

This is really awesome.

Add swagger and swagger-ui to your project

Now lets bring it together with laravel

At first you need l5-swagger. This is a cli extension for laravel

Add "darkaonline/l5-swagger": "~3.0 to your composer.json and make "composer update"

Add module creator to your cli

add "artem-schander/l5-modular": "^1.3" to your composer.json and make "composer update"

At first you need l5-swagger. This is a cli extension for laravel

Add "darkaonline/l5-swagger": "~3.0 to your composer.json and make "composer update"

Generate a module

Switch to your laravel project root

php artisan make:module Api 

This will create a Module Api under "app/modules"

Add annotation to your controller

Swagger annotations will describe your Api in a json format. So that it can be used to create a nice webapplication for your Api methods including a complete documentation.

Add a controller like that

As you can see you a lot of annotation there. Do not feel overvelmed from that. It is definetly worth a try. The benefit is a really smooth webui for your documentation within a REST Client for each method. This will definetly be a sales pitch for your Apis.

If you have set the routing to reach you api methods, you can generate the swagger.json by calling the artisan cli like that

php artisan l5-swagger:generate

This will generate a file "<approot>/storage/api-docs/api-docs.json"

Point your browser to that file and copy the url

Start swagger-ui

Open your browser and open a file "<swagger-ui/dist/index.htm>" from the filemenu in your browser

At that you will get the swagger ui.
Now you can paste the swagger.json url to the searchfield an hit "explore"


Now you will see your api documentation:

Thats awesome