Laravel 安装 l5-swagger 扩展 让项目支持 Swagger
背景
用 Laravel 作为 API 支持框架,如果能够在写代码的过程,随便就把文档写了,那么是不是感觉很方便呢。
安装过程
当前操作默认在项目 根目录:
-
使用 composer 添加该包
composer require darkaonline/l5-swagger
-
生成配置文件到 config 目录,可以自行去看看其中配置项
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
-
跑起来
php artisan serve
Laravel development server started: http://127.0.0.1:8000
- 浏览器访问
浏览器打开:http://127.0.0.1:8000/api/documentation
安装完毕
具体使用
刚接触它时候,我是拒绝的,总想用已知的东西来否认逃避去了解它,为什么不用 postman 呢?当出现这个想法的时候,我变成了
锤子
,面对所有的问题 都把它 想成钉子
,咬牙看完swagger
文档后,才知:锤子+1
。
L5-Swagger 是什么?
是 laravel 的一个扩展包,结合
swagger-php
+swagger-ui
,使我们能够在编写代码的时候,通过编写注释,生成 API 接口文档,并且可直接在开发的项目上直接访问这些 API 接口。
第一步:编写可生成API文档的注释
解析注释生成 API 文档的的功臣是
swagger-php
,所以要安照它的使用方法来,它的 github 地址是:swagger-php 下面的内容假设在你已经了解了 swagger 的相关语法。
如:
<?php
/**
* @SWG\Info(title="Test", version="0.0.1")
*/
// 别直接复制这里的注释,缩进破坏了,
// 请上 github 上复制它的用例。这里只作为演示作用
class MyController
{
/**
* @SWG\Get(
* path="/api/syahi",
* @SWG\Response(response="200", description="An example resource")
* )
*/
public function say()
{
return ['msg' => 'Hello World'];
}
// Other Code...
}
注意 我用的版本是 swagger-php 2.x
,所以注释使用的是 @SWG
,现在最新版本使用的是 @OA
做为标识(OpenApi 首字母)。
想了解更多,可以上 github,到该项目的演示项目参考其它注释方法:Examples
第二步:生成 API 文档
编写完上面的注释,运行此命名:
php artisan l5-swagger:generate
它会生成 API 文档,默认在项目根目录: storage\api-docs\api-docs.json
,如:
第三步:浏览器访问
当然可以配置自动生成 API文档,请自行到 L5-Swagger 取经!
后话
- 本文只是做一个入门的指引,解决最基本的问题:跑起来。
- 本人是在接触 swagger 不到 24 小时内,要求项目中使用它,文章肯定有不足的地方,请各位谅解!
- 现在接触下来,发现 swagger 很方便。
- 见与你有缘,有一篇: 如何编写基于 Swagger-PHP 的 API 文档 能助你轻松掌握 swager-php!
本作品采用《CC 协议》,转载必须注明作者和本文链接
推荐文章: