How to quickly generate Laravel API documentation using DocGen

As a backend developer we know that documenting the data of our API is necessary during the progress of the project and the difficult part is that they have to be taken care of constantly as we may update the routes and so the related documentations should be updated too.

So a single source of truth is needed in a way that whenever our code is updated, the documentation updates by itself consequently. That source of truth is the code itself of course, thus a documentation generator tool that keeps eye on the code can be really useful to handle the API documentation.

There are lots of API tools that generate documentation, like Swagger which is really powerful and gives a pretty nice output view but the problem with most of these generator tools is that they don’t use the single source of truth.

So because managing an API documentation sounds boring and time consuming to me, I managed to build a package that generates an API documentation for my service which gives the front-end team a basic knowledge about the routes e.g. request body, output variables, whether the route requires authentication or not, middlewares and etc.

In this tutorial I’m going to introduce the waxwink/docgen package to those who need to create a basic API documentation right away.

Installation

First require the waxwink/docgen package in the project:

composer require waxwink/docgen

Then add the service provider to the config file:

Waxwink\DocGen\Providers\DocGenServiceProvider::class,

Finally publish the vendor files to the public folder:

php artisan vendor:publish --tag=public

And now you are ready to go

Getting started

As soon as you have installed the package you have access to the “/routes” URI and a complete list of all the routes of the project including web and api can be seen in it.

If you need the request body of every routes then each of your controllers should have a FormRequest object as an input parameter so DocGen can analyze the request body from the form request object. For example this is the store method of PostController:

/**
 * Store a newly created resource in storage.
 *
 * @param PostRequest $request
 * @return void
 */
public function store(PostRequest $request)
{
    return Post::create($request->all());
}

The PostRequest object has the following rules:

/**
 * Get the validation rules that apply to the request.
 *
 * @return array
 */
public function rules()
{
    return [
        'title' => 'required',
        'body' => 'required'
    ];
}

Now when you check the “/routes” again you will see that the request body is included in the “/posts” POST method :

The request body is added automatically to the route doc

The Output Keys

If you need the response keys of the routes to be included then their controller method should return a JsonResource object. DocGen must be aware of this resource by putting it as doc block (with “@DG-Resource”) in the controller method as follows:

/**
 * Store a newly created resource in storage.
 *
 * @DG-Resource App\Http\Resources\PostResource
 *
 * @param PostRequest $request
 * @return PostResource
 */
public function store(PostRequest $request)
{
    return PostResource::make(Post::create($request->all()));
}

The PostResource file returns these keys:

/**
 * Transform the resource into an array.
 *
 * @param  Request  $request
 * @return array
 */
public function toArray($request)
{
    return [
        'title'=> $this->title,
        'body'=> $this->body,
    ];
}

Now by refreshing the “/routes” page again you will see that the output key has beed updated too:

The output keys are automatically resolved by the output json resource of the controller method

Conclusion

During this tutorial we just built a minimal API documentation which uses the application codes to resolve the request body and the response body keys of the API routes which can be really helpful especially when there is no time to make a complete documentation.