PHP code example of johnylemon / laravel-apidocs

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

johnylemon / laravel-apidocs example snippets

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');
    }
}

$this->uri('/users');

$this->method('POST');

$this->group('some-group-slug');

$this->deprecated();

$this->title('Create user resource');

$this->description('This endpoint contains logic for creating user resources based on provided data');

$this->query([
    'page' => Param::type('int')
])

$this->query([
    'page' => Param::type('int')
])

$this->query([
    'page' => Param::type('int')
])

$this->header('x-johnylemon', 'apidocs')

$this->headers([
    'x-johnylemon' => 'apidocs',
    'x-laravel' => 'framework'
])

$this->example([
    'name' => 'johnylemon',
    'web' => 'https://johnylemon.dev',
    'email' => '[email protected]'
], 'Store user')

$this->examples([
    [
        'name' => 'johny',
        'web' => 'https://johnylemon.dev',
        'email' => '[email protected]'
    ],
    [
        'name' => 'lemon',
        'web' => 'https://johnylemon.dev',
        'email' => '[email protected]'
    ]
])

$this->returns(201, [
    'name' => 'johny',
    'web' => 'https://johnylemon.dev',
    'email' => '[email protected]'
], 'User created')
->returns(401, [
    'status' => 'unauthorized',
], 'Auth issue');

// calling this ...
$this->returns201([
    'name' => 'johny',
    'web' => 'https://johnylemon.dev',
    'email' => '[email protected]'
], 'User created');

// ... is equivalent of this...

$this->returns(201, [
    'name' => 'johny',
    'web' => 'https://johnylemon.dev',
    'email' => '[email protected]'
], 'User created')

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

use App\Apidocs\Endpoints\SampleEndpoint;

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

use App\Apidocs\Endpoints\SampleEndpoint;

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

Route::resource('posts', PostsController::class)->apidocs([
    'posts.index' => PostsIndexEndpoint::class,
    'posts.store' => PostStoreEndpoint::class,
]);

//
// your resoures
//
Route::resources([
    'users' => UsersController::class,
    'posts' => PostsController::class,
]);

//
// defining endpoints
//
apidocs([
    'posts.index'   => PostsIndexEndpoint::class,
    'posts.store'   => PostStoreEndpoint::class,
    'users.index'   => UsersIndexEndpoint::class,
    'users.store'   => UserStoreEndpoint::class,
    'users.destroy' => UserStoreEndpoint::class,
]);

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')
            ->query([
                Param::int('page')->example(1)->default(1)->optional()
            ])
    }
}

use Johnylemon\Apidocs\Facades\Param;

$this->query([

    // parameter name will be `page`
    Param::int('page')->example(1)->default(1)->optional()

    // same effect:
    'page' => Param::int('page')->example(1)->default(1)->optional()

    // same effect:
    'page' => Param::type('int')->example(1)->default(1)->optional()

    // this parameter will be named `page_number`
    'page_number' => Param::int('page')->example(1)->default(1)->optional()
])

Param::type('int');

Param::name('username');

Param::description('Unique username');

Param::

Param::optional();

Param::possible([10, 100, 1000]);

Param::enum([10, 100, 1000]);

Param::default(42);

Param::example(42);

use Johnylemon\Apidocs\Facades\Param;

$this->query([
    Param::string('slug'), // `slug` property, that should have `string` type
    Param::int('id'), // id `property`, that should have `int` type
    Param::array('roles'), // `roles` property, that should have `array` type
])

$this->query([
    Param::int('page')->example(1)->default(1)->optional()
]);

use App\Apidocs\Params\PageParam;

(...)

$this->query([
    PageParam::class
]);

php artisan apidocs:param PageParam

namespace App\Apidocs\Params;

use Johnylemon\Apidocs\Params\Param;

class PageParam extends Param
{
    public function __construct()
    {
        $this->name('page')->type('int')->default(1)->eg(42)->optional();
    }
}

use Johnylemon\Apidocs\Facades\Apidocs;

Apidocs::defineGroup('users', 'Users', 'Manage users');
Apidocs::defineGroup('tickets', 'Tickets'); // Last parameter is optional

php artisan apidocs:install

php artisan apidocs:endpoint SampleEndpoint