PHP Apidocs generation tool

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

1. Add johnylemon/laravel-apidocs repository

composer require johnylemon/laravel-apidocs

1. Register Johnylemon\Apidocs\Providers\ApidocsServiceProvider provider if not registered automagically .

2. Install package. This command will publish all required assets.
   

php artisan apidocs:install

1. 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.

Comments

[Gregori Piñeres]

I don't like annotations either, I started building my own package but I haven't been able to spend more time on it.

github.com/gregorip02/openapi-gene...

PS. Thanks for building it 👋