使用 Laravel API 文档生成器扩展包自动为项目生成 API 文档
1、安装配置
Laravel API 文档生成器扩展包可以基于 Laravel 应用路由自动生成项目 API 文档。
我们使用Composer安装这个扩展包：
$ composer require mpociot/laravel-apidoc-generator
安装完成后需要到config/app.php中注册服务提供者（Laravel 5.5 及以上版本不需要手动注册，会自动发现）：
Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,
然后将该扩展包的配置文件发布 config 目录下：
php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config
2、使用
基本示例
下面我们来演示如何使用这个扩展包自动为项目生成API文档，其原理是通过扫描routes.php为指定路由生成相应API文档，比如我们的路由文件定义了一个路由如下：
Route::get('api/v1/index', 'ApiController@index');
这个路由对应的控制器方法定义如下：
/**
* API首页
*
* 欢迎来到Laravel学院，Laravel学院致力于提供优质Laravel中文学习资源
*
*/
public function index()
{
}
需要指出的是，Laravel API 生成器通过action方法上的注释生成 API 相应的描述信息。我们使用扩展包提供的api:generate命令来实现 API 文档生成：
php artisan api:generate --routePrefix=api/v1/*
该命令的意思是扫描路由中匹配api/v1/*的规则并为相应控制器方法生成API文档，该命令会在public目录下生成一个docs目录以及相应文件，我们在浏览器中通过http://blog.dev/docs/index.html（我的域名是blog.dev）来查看API文档：
带响应数据的示例
上面是一个最简单的示例，大部分时候我们的action会返回HTTP响应，这种情况下API文档又是如何显示的呢？
我们在路由文件routes.php中定义一个路由如下：
Route::get('api/v1/test', 'ApiController@test');
对应的控制器方法定义如下：
/**
* API响应测试
*
* 这是一个API响应测试页面
*
*/
public function test()
{
return new Response('Laravel学院,优质Laravel中文学习资源平台');
}
我们在action中简单返回一个带字符串信息的Response，要生成该方法的API文档，还是要运行api:generate命令：
php artisan api:generate --routePrefix=api/v1/*
运行完成后，再次访问http://blog.dev/docs/index.html，就可以看到API响应测试信息：
在右下角我们可以看到响应数据信息。
如果需要认证用户才能调用API，可以在生成API文档的时候加个--actAsUser选项并指定用户ID：
php artisan api:generate --routePrefix=api/v1/* --actAsUserId=1
带参数的API
下面我们来看一个更加复杂的例子，有时候我们提交POST请求到某个API时会带参数，这个时候如何生成带参数的API文档信息呢？很简单，我们只需按照之前的正常逻辑走，然后运行下api:generate命令即可。
我们定义一个post请求路由如下：
Route::post('api/v1/params', 'ApiController@params');
在定义应控制器方法之前我们先通过如下命令生成一个请求类：
php artisan make:request TestRequest
这会在app/Http/Requests目录下新生成一个TestRequest类，我们编辑该类的rules方法如下：
public function rules()
{
return [
'title' => 'required|max:255',
'body' => 'required',
'type' => 'in:foo,bar',
'thumbnail' => 'required_if:type,foo|image',
];
}
接下来再去控制器中定义相应方法：
/**
* API请求参数
*
* 测试API请求参数
*
* @param Requests\TestRequest $request
*/
public function params(Requests\TestRequest $request)
{
}
我们在控制器方法中通过依赖注入传入我们刚刚创建的TestRequest类。
最后还是按部就班，通过api:generate命令生成新的API文档：
php artisan api:generate --routePrefix=api/v1/*
在浏览器中访问http://blog.dev/docs/index.html，在页面中我们可以看到带参数的API文档信息：
更多使用
如果觉得默认的API文档模板太丑陋，该扩展包还提供了api:update命令修改默认API文档模板，其操作流程是先修改index.md文件（位于public/docs/source/index.md），修改好了之后通过如下命令保存修改：
php artisan api:update
这个功能很简单，这里就不做演示了。了解更多请参考该扩展的GitHub项目：https://github.com/mpociot/laravel-apidoc-generator/。
39 Comments