library l5-api-documentor

g-six/l5-api-documentor

Generate beautiful API documentation from your Laravel application

Laravel API Documentation Generator

Automatically generate your API documentation from your existing Laravel routes. Take a look at the example documentation., _(*1)

After a month of customising since forking from https://github.com/mpociot/laravel-apidoc-generator, there are a lot of changes made to fit our laravel base code ecosystem., _(*2)

Please take note of the changes in options below as they are different from Mpociot's original code. Great work @mpociot., _(*3)

php artisan api:gen --routePrefix="settings/api/*", _(*4)

Installation

Require this package with composer using the following command:, _(*5)

$ composer require g-six/l5-api-documentor

Go to your config/app.php and add the service provider:, _(*6)

G6\ApiDoc\ApiDocGeneratorServiceProvider::class,

Using Laravel < 5.4? Use version 1.0! For Laravel 5.4 and up, use 2.0 instead., _(*7)

Usage

To generate your API documentation, use the api:generate artisan command., _(*8)

$ php artisan api:generate --routePrefix="api/v1/*"

This command will scan your applications routes for the URIs matching api/v1/* and will parse these controller methods and form requests. For example:, _(*9)

// API Group Routes
Route::group(array('prefix' => 'api/v1', 'middleware' => []), function () {
    // Custom route added to standard Resource
    Route::get('example/foo', 'ExampleController@foo');
    // Standard Resource route
    Route::resource('example', 'ExampleController'));
});

Available command options:

Publish rule descriptions for customisation or translation.

By default, this package returns the descriptions in english. You can publish the packages language files, to customise and translate the documentation output., _(*10)

sh $ php artisan vendor:publish, _(*11)

After the files are published you can customise or translate the descriptions in the language you want by renaming the en folder and editing the files in public/vendor/apidoc/resources/lang., _(*12)

How does it work?

This package uses these resources to generate the API documentation:, _(*13)

Controller doc block

This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods., _(*14)

Using @resource in a doc block prior to each controller is useful as it creates a Group within the API documentation for all methods defined in that controller (rather than listing every method in a single list for all your controllers), but using @resource is not required. The short description after the @resource should be unique to allow anchor tags to navigate to this section. A longer description can be included below., _(*15)

Above each method within the controller you wish to include in your API documentation you should have a doc block. This should include a unique short description as the first entry. An optional second entry can be added with further information. Both descriptions will appear in the API documentation in a different format as shown below., _(*16)

/**
 * @resource Example
 *
 * Longer description
 */
class ExampleController extends Controller {

    /**
     * This is the short description [and should be unique as anchor tags link to this in navigation menu]
     *
     * This can be an optional longer description of your API call, used within the documentation.
     *
     */
     public function foo(){

     }

Result:, _(*17)

, _(*18)

Form request validation rules

To display a list of valid parameters, your API methods accepts, this package uses Laravels Form Requests Validation., _(*19)

public function rules()
{
    return [
        'title' => 'required|max:255',
        'body' => 'required',
        'type' => 'in:foo,bar',
        'thumbnail' => 'required_if:type,foo|image',
    ];
}

Result: , _(*20)

API responses

If your API route accepts a GET method, this package tries to call the API route with all middleware disabled to fetch an example API response., _(*21)

With Mpciot's version, if your API needs an authenticated user, you can use the actAsUserId option to specify a user ID that will be used for making these API calls, this doesn't work with our base code, so we added the --auth option with parameters required by our auth., _(*22)

$ php artisan api:generate --routePrefix="api/*" --auth={"admin": {"username": "username", "password": "some password", "type": "admin"}}

If you don't want to automatically perform API response calls, use the noResponseCalls option., _(*23)

$ php artisan api:generate --routePrefix="api/*" --noResponseCalls

Note: The example API responses work best with seeded data., _(*24)

Postman collections

The generator automatically creates a Postman collection file, which you can import to use within your Postman App for even simpler API testing and usage., _(*25)

If you don't want to create a Postman collection, use the --noPostmanCollection option, when generating the API documentation., _(*26)

As of as of Laravel 5.3, the default base URL added to the Postman collection will be that found in your Laravel config/app.php file. This will likely be http://localhost. If you wish to change this setting you can directly update the url or link this config value to your environment file to make it more flexible (as shown below):, _(*27)

'url' => env('APP_URL', 'http://yourappdefault.app'),

If you are referring to the environment setting as shown above, then you should ensure that you have updated your .env file to set the APP_URL value as appropriate. Otherwise the default value (http://yourappdefault.app) will be used in your Postman collection. Example environment value:, _(*28)

APP_URL=http://yourapp.app

Skip single routes

If you want to skip a single route from a list of routes that match a given prefix, you can use the @hideFromAPIDocumentation tag on the Controller method you do not want to document., _(*29)

License

The Laravel API Documentation Generator is free software licensed under the MIT license forked (https://github.com/mpociot/laravel-apidoc-generator) and customized to work with our team's base code., _(*30)