使用LaravelAPI文档生成器扩展包自动为项目生成API文档

内容导读

互联网集市收集整理的这篇技术教程文章主要介绍了使用LaravelAPI文档生成器扩展包自动为项目生成API文档，小编现在分享给大家，供广大互联网技能从业者学习和参考。文章包含3467字，纯文字阅读大概需要5分钟。

内容图文

1、简介&安装

Laravel API 文档 生成器 扩展包可以基于 Laravel 应用路由自动生成项目 API 文档。

我们使用Composer安装这个扩展包：

$ composer require mpociot/laravel-apidoc-generator

安装完成后需要到 config/app.php 中注册服务提供者：

Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

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/ 。

内容总结

以上是互联网集市为您收集整理的使用LaravelAPI文档生成器扩展包自动为项目生成API文档全部内容，希望文章能够帮你解决使用LaravelAPI文档生成器扩展包自动为项目生成API文档所遇到的程序开发问题。 如果觉得互联网集市技术教程内容还不错，欢迎将互联网集市网站推荐给程序员好友。

内容备注

版权声明：本文内容由互联网用户自发贡献，该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 gblab@vip.qq.com 举报，一经查实，本站将立刻删除。

内容手机端