PHP Apidocs generation tool

Piotr Krzempek — Sun, 13 Dec 2020 15:55:05 +0000

I don't like writing tons of lines of stupid annotations just to have hope that api documentation will be generated correctly without errors that says nothing. And I am not the only one.

So I created package that solves this problem the way I like - by writing PHP code.

Can be found here: Laravel Apidocs

This way you can:

reuse, extend and modify existing api definitions
create generic endpoint definitions and just modify them ad-hoc or by creating child classes
define multiple examples
define multiple sample responses
define and reuse parameter definitions
make your controllers readable again

Getting started

Add johnylemon/laravel-apidocs repository

composer require johnylemon/laravel-apidocs

Register Johnylemon\Apidocs\Providers\ApidocsServiceProvider provider if not registered automagically .
Install package. This command will publish all required assets.

php artisan apidocs:install

Enjoy!

Generating route documentation

Package ships with command for rapid route definition generation.

php artisan apidocs:endpoint SampleEndpoint

Brand new SampleEndpoint class will be placed within app\Apidocs\Endpoints directory.
Target directory may be changed within your apidocs config file.

This class contains only one describe method, where you have to use any of available methods that will describe your endpoint. Like that:

<?php

namespace App\Apidocs\Endpoints;

use Johnylemon\Apidocs\Endpoints\Endpoint;
use Johnylemon\Apidocs\Facades\Param;

class SampleEndpoint extends Endpoint
{
    public function describe(): void
    {
        $this->title('List users')
            ->desc('Returns paginated list of users');
    }
}

As you can see we set title and description as endpoint definition.
Every method returns endpoint instance so you can chain them.

Endpoint definition usage

Okay, you created your first endpoint definition. Now it's time to use it as some real route definition.

Lets assume you have following routes:


Route::get('api/users', [UsersController::class, 'index']);

If you want to use App\Apidocs\Endpoints\SampleEndpoint class as definition for first of them you should simply do this:


use App\Apidocs\Endpoints\SampleEndpoint;

Route::get('api/users', [UsersController::class, 'index'])->apidocs(SampleEndpoint::class);

and... yes, thats it!

The only thing you have to do now is to call php artisan apidocs:generate command and visit /apidocs route to see it in action!

Look at github package page to learn more!

Developed with ❤ by johnylemon.

DEV Community: Piotr Krzempek

PHP Apidocs generation tool

Getting started

Generating route documentation

Endpoint definition usage