Cherry-Pie / ApiDocs by Cherry Pie

Api documentation generator for Laravel 5
4,066
10
2
Package Data
Maintainer Username: Cherry Pie
Maintainer Contact: 12fcv4@gmail.com (Yaro)
Package Create Date: 2017-06-26
Package Last Update: 2020-05-10
Home Page:
Language: HTML
License: MIT
Last Refreshed: 2024-10-31 15:03:56
Package Statistics
Total Downloads: 4,066
Monthly Downloads: 0
Daily Downloads: 0
Total Stars: 10
Total Watchers: 2
Total Forks: 4
Total Open Issues: 0

ApiDocs Generator

Scrutinizer Code Quality Build Status

L5 API Documentation generator based upon DocBlock comments.

Installation

You can install the package through Composer:

composer require yaro/apidocs

Add this service provider and alias to config/app.php:

'providers' => [
    //...
    Yaro\ApiDocs\ServiceProvider::class,
    //...
]

'aliases' => [
    //...
    'ApiDocs' => Yaro\ApiDocs\Facade::class,
    //...
]

Then publish the config and assets files:

php artisan vendor:publish --provider="Yaro\ApiDocs\ServiceProvider"

And you should add a disk named snapshots to config/filesystems.php on which the blueprint snapshots will be saved:

//...
'disks' => [
    //...
    'apidocs' => [
        'driver' => 'local',
        'root'   => storage_path('apidocs'),
    ],
//...    

Usage

All your routes must begin with some segment, e.g. /api/ (changed in config). Package will collect routes, that starts with this segment only.

Add to your route method DocBlock comment. e.g.:

/**
 * Some api endpoint for important stuff.
 * 
 * Just show some template with     
 * some very long description    
 * on several lines
 * 
 * @param int    $offset   Just an offset size
 * @param string $password 
 */
public function getSomeStuff()
{
    return response()->json([]);
}

And create route to view your documentation.

Route::get('/docs', function() {
    return ApiDocs::show();
});

Also you can force authorization prompt by adding apidocs.auth.basic middleware. Authorized identites placed under apidocs.auth.credentials config.

Route::get('/docs', function() {
    return ApiDocs::show();
})->middleware(['apidocs.auth.basic']);

To exclude some routes/classes add them to config's exclude. Asterisks may be used to indicate wildcards.

'exclude' => [
    'classes' => [
        // 'App\Http\Controllers\*' - exclude all controllers from docs.
        // 'App\Http\Controllers\MyController@*' - remove all methods for specific controller from docs.
    ],
    
    'routes' => [
        // 'payment/test',
        // 'simulate/*',
    ],
 ],

Additionally you can create API Blueprint file:

ApiDocs::blueprint()->create();
// or pass snapshot name and/or filesystem disc name
ApiDocs::blueprint()->create('my-newest-snapshot', 's3-blueprint');

Or just render its contents without creating file:

echo ApiDocs::blueprint()->render();

Or via artisan:

php artisan apidocs:blueprint-create

TODO

  • generate plain html page with all documentation info.
  • fullsize block with response.

License

The MIT License (MIT). Please see LICENSE for more information.