Laravel API Documentation Generator is a cool package that we can use to automatically generate our Laravel API Documentation. In this post, I’m going to write about the Laravel API Documentation Generator in the easy and simple way.
Laravel API Documentation Generator
It is Automatically generate your API Documentation from your existing Laravel routes.
It have language bindings in Shell, Ruby, and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
This example API Documentation page was created with Whiteboard. Feel free to edit it and use it as a base for your own API’s documentation.
Step 1: Generate API Documentation
php artisan api:gen --routePrefix=settings/api/*
Step 2: Installation
Require this package with composer using the following command:
$ composer require mpociot/laravel-apidoc-generator
Using Laravel < 5.5? Go to your config/app.php and add the service provider:
Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,
Using Laravel < 5.4? Use version 1.0! For Laravel 5.4 and up, use 2.0 instead.
Step 3: Usage
To generate your API documentation, use the api:generate artisan command.
$ 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:
// 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');
});
Step 4: 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.
$ php artisan vendor:publish
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.
How Laravel API Documentation Generator work?
This package uses these resources to generate the API documentation:
Controller doc block
This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods.
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.
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.
/**
* @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(){
}
Modify the generated documentation
If you want to modify the content of your generated documentation, go ahead and edit the generated index.md file. The default location of this file is: public/docs/source/index.md.
After editing the markdown file, use the api:update command to rebuild your documentation as a static HTML file.
$ php artisan api:update
As an optional parameter, you can use --location to tell the update command where your documentation can be found.
For more, you should follow the Documentation
