主业iOS/PHP,副业啥都玩,QQ:705719110,欢迎来撩!

使用 Laravel API 文档生成器扩展包为项目生成 API 文档

PHP开发 随风 455℃ 0评论

1、简介&安装

Laravel API 文档生成器扩展包可以基于 Laravel 应用路由自动生成项目 API 文档。
我们使用Composer安装这个扩展包:

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

2、使用

下面我们来演示如何使用这个扩展包自动为项目生成API文档,其原理是通过扫描routes.php为指定路由生成相应API文档,比如我们的路由文件定义了一个路由如下:

这个路由对应的控制器方法定义如下:

需要指出的是,Laravel API 生成器通过action方法上的注释生成 API 相应的描述信息。我们使用扩展包提供的api:generate命令来实现 API 文档生成:

该命令的意思是扫描路由中匹配api/v1/*的规则并为相应控制器方法生成API文档,该命令会在public目录下生成一个docs目录以及相应文件,我们在浏览器中通过http://blog.dev/docs/index.html(我的域名是blog.dev)来查看API文档:

laravel-api-doc-index

上面是一个最简单的示例,大部分时候我们的action会返回HTTP响应,这种情况下API文档又是如何显示的呢?
我们在路由文件routes.php中定义一个路由如下:

对应的控制器方法定义如下:

我们在action中简单返回一个带字符串信息的Response,要生成该方法的API文档,还是要运行api:generate命令:

运行完成后,再次访问http://blog.dev/docs/index.html,就可以看到API响应测试信息:

laravel-api-doc-response

在右下角我们可以看到响应数据信息。
如果需要认证用户才能调用API,可以在生成API文档的时候加个–actAsUser选项并指定用户ID:

带参数的API
下面我们来看一个更加复杂的例子,有时候我们提交POST请求到某个API时会带参数,这个时候如何生成带参数的API文档信息呢?很简单,我们只需按照之前的正常逻辑走,然后运行下api:generate命令即可。

我们定义一个post请求路由如下:

在定义应控制器方法之前我们先通过如下命令生成一个请求类:

这会在app/Http/Requests目录下新生成一个TestRequest类,我们编辑该类的rules方法如下:

接下来再去控制器中定义相应方法:

我们在控制器方法中通过依赖注入传入我们刚刚创建的TestRequest类。
最后还是按部就班,通过api:generate命令生成新的API文档:

在浏览器中访问http://blog.dev/docs/index.html,在页面中我们可以看到带参数的API文档信息:

laravel-api-doc-params

如果觉得默认的API文档模板太丑陋,该扩展包还提供了api:update命令修改默认API文档模板,其操作流程是先修改index.md文件(位于public/docs/source/index.md),修改好了之后通过如下命令保存修改:

这个功能很简单,这里就不做演示了。了解更多请参考该扩展的GitHub项目:https://github.com/mpociot/laravel-apidoc-generator/

转载请注明:怼码人生 » 使用 Laravel API 文档生成器扩展包为项目生成 API 文档

喜欢 (0)
发表我的评论
取消评论

表情

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址