Laravel筆記之 集成API文檔工具Swagger

目錄

一、新建一個laravel項目

二、集成Swagger

1、獲取darkaonline/l5-swagger

2、註冊組件

3、創建swagger-UI等

4、創建swagger配置文件

5、訪問測試

6、添加測試API

---

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' => '[email protected]'
                    ]
                ],
            ],
            'message'   => '',
            'type'      => 'success',
            'status'    => 0
        ]);
    }
}

添加下路由

Route::get('test', 'TestController@index');

最終效果如下 

---

參考：
Integrate Swagger API documentation with Laravel Project (L5 Swagger)