# 在laravel中集成swagger

swagger是非常好用的一个API文档工具,大大地减轻了前端和后端的沟通成本。在写后端接口的时候,也可以用它来测试接口,非常方便。 整个过程如下。

# 新建一个laravel项目

composer create-project --prefer-dist laravel/laravel Blog

# 获取darkaonline/l5-swagger

composer require "darkaonline/l5-swagger"

# 注册组件

在config/app.php的providers中添加\L5Swagger\L5SwaggerServiceProvider::class,

# 创建swagger-UI等

php artisan l5-swagger:publish

# 创建swagger配置文件

php artisan l5-swagger:publish-config 

执行该命令后,会在config目录下产生一个l5-swagger.php的配置文件,里面包含了swagger标题,token验证,路由等。

其中'generate_always'配置可以根据需要修改下,它表示是否每次都刷新swagger。如果是关闭,则修改swagger配置后,要使用php artisan l5-swagger:generate命令手动刷新。

# 访问测试

在浏览器访问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

# 添加测试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)