Automatically generate API documentation for your project using the Laravel API Document Builder extension Package

1. Introduction & Installation

The Laravel API Document Generator extension package can automatically generate project API documentation based on Laravel app routing.

We use composer to install this expansion pack:

$ composer require Mpociot/laravel-apidoc-generator

After the installation is complete, you need to register the service provider in config/app.php:

Mpociot\apidoc\apidocgeneratorserviceprovider::class,

2. Use

Basic example

Let's show how to use this extension package to automatically generate API documentation for a project by scanning routes.php to generate the appropriate API documentation for the specified route, for example, our routing file defines a route as follows:

Route::get (' Api/v1/index ', ' apicontroller@index ');

The Controller method corresponding to this route is defined as follows:

/** * API Home * Welcome to Laravel College, Laravel College is committed to providing quality laravel Chinese learning resources * */public Function Index () {}

It should be noted that the Laravel API generator generates the appropriate descriptive information for the API through comments on the action method. We use the Api:generate command provided by the expansion pack to implement API document generation:

PHP Artisan api:generate--routeprefix=api/v1/*

This command means scanning the rules in the route matching api/v1/* and generating the API documentation for the corresponding controller method, which generates a docs directory and the corresponding file in the public directory, and we pass the http://blog.dev/docs/in the browser index.html (my domain name is Blog.dev) to view the API documentation:

Example with response data

This is the simplest example, and most of the time our action returns an HTTP response, in which case how does the API document appear?

We define a route in the routing file routes.php as follows:

Route::get (' api/v1/test ', ' apicontroller@test ');

The corresponding controller method is defined as follows:

/** * API Response Test * * This is an API Response test page * */public function test () {    return new Response (' Laravel College, quality laravel Chinese Learning Resource Platform ');}

We simply return a response with string information in action, to generate the API documentation for the method, or to run the api:generate command:

PHP Artisan api:generate--routeprefix=api/v1/*

Once the operation is complete, access the http://blog.dev/docs/index.html again to see the API response Test information:

In the lower right corner we can see the response data information.

If you need to authenticate the user to invoke the API, you can add a--actasuser option and specify the user ID when generating the API documentation:

PHP Artisan api:generate--routeprefix=api/v1/*--actasuserid=1

API with Parameters

Let's look at a more complex example, and sometimes when we submit a POST request to an API with parameters, how can we generate API documentation with parameters? Very simply, we just follow the normal logic, then run the next api:generate command.

We define a POST request route as follows:

Route::p ost (' Api/v1/params ', ' apicontroller@params ');

Before defining the Controller method, we will first generate a request class with the following command:

PHP Artisan make:request testrequest

This will be reborn as a testrequest class in the App/http/requests directory, and we'll edit the rules method for that class as follows:

Public Function Rules () {    return [        ' title ' = ' required|max:255 ',        ' body ' = ' required ',        ' type ' = > ' In:foo,bar ',        ' thumbnail ' = ' required_if:type,foo|image ',    ];}

Then go to the controller to define the appropriate method:

/** * API Request Parameters * * Test API Request Parameters * * @param requests\testrequest $request */public function params (requests\testrequest $reques T) {    }

We passed the dependency injection in the Controller method to the Testrequest class we just created.

Finally, step by step, generate a new API document with the Api:generate command:

PHP Artisan api:generate--routeprefix=api/v1/*

To access http://blog.dev/docs/index.html in the browser, we can see the API document information with parameters in the page:

More use

If you feel that the default API document template is too ugly, the extension package also provides the api:update command to modify the default API document template, whose operation is to first modify the Index.md file (located in public/docs/source/index.md), After you have modified it, save the changes by following this command:

PHP Artisan Api:update

This is a very simple function and it is not a demonstration. For more information, refer to the GitHub project for this extension: https://github.com/mpociot/laravel-apidoc-generator/