目录
Swagger是非常好用的一个API文档工具,大大地减轻了前端和后端的沟通成本。在写后端接口的时候,也可以用它来测试接口,非常方便。
整个过程如下:
一、新建一个laravel项目
composer create-project --prefer-dist laravel/laravel Blog
二、集成Swagger
1、获取darkaonline/l5-swagger
composer require "darkaonline/l5-swagger"
2、注册组件
在 config/app.php 的 providers 中添加 \L5Swagger\L5SwaggerServiceProvider::class,
3、创建swagger-UI等
php artisan l5-swagger:publish
4、创建swagger配置文件
php artisan l5-swagger:publish-config
执行该命令后,会在config目录下产生一个l5-swagger.php的配置文件,里面包含了swagger标题,token验证,路由等。
其中’generate_always’配置可以根据需要修改下,它表示是否每次都刷新swagger。如果是关闭,则修改swagger配置后,要使用 php artisan l5-swagger:generate 命令手动刷新。
5、访问测试
在浏览器访问http://127.0.0.1/api/documentation,可以看到swagger的界面了,但会提示缺少api-docs.json文件。
可以在app下创建个php文件,如swagger.php,内容如下
<?php
/**
* Class Controller
*
* @package App\Http\Controllers
*
* @SWG\Swagger(
* basePath="",
* host="127.0.0.1",
* schemes={"http"},
* @SWG\Info(
* version="1.0",
* title="OpenApi",
* @SWG\Contact(name="Pek Ratanak", url="https://www.google.com"),
* ),
* @SWG\Definition(
* definition="Error",
* required={"code", "message"},
* @SWG\Property(
* property="code",
* type="integer",
* format="int32"
* ),
* @SWG\Property(
* property="message",
* type="string"
* )
* )
* )
*/
刷新下swagger,重新访问
php artisan l5-swagger:generate
6、添加测试API
比如创建一个test的TestController
php artisan make:controller TestController
内容如下
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class TestController extends Controller
{
/**
* @SWG\Get(
* path="/api/test",
* description="返回测试内容",
* operationId="api.dashboard.index",
* produces={"application/json"},
* tags={"测试"},
* @SWG\Parameter(
* in="formData",
* name="reason",
* type="string",
* description="拿数据的理由",
* required=true,
* ),
* @SWG\Response(
* response=200,
* description="Dashboard overview."
* ),
* @SWG\Response(
* response=401,
* description="Unauthorized action.",
* )
* )
*/
public function index(Request $request)
{
return response()->json([
'result' => [
'statistics' => [
'users' => [
'name' => 'Name',
'email' => 'user@example.com'
]
],
],
'message' => '',
'type' => 'success',
'status' => 0
]);
}
}
添加下路由
Route::get('test', 'TestController@index');
最终效果如下
参考:
Integrate Swagger API documentation with Laravel Project (L5 Swagger)