本篇講述在如何快速在Laravel中引入Swagger並開始使用。

安裝

首先是使用Laravel的一個composer：L5 Swagger。
下面是對應的各個版本。

下面的過程全部基於Laravel 5.5.x
在Laravel根目錄下執行一下命令
composer require "darkaonline/l5-swagger:5.5.*"
等待安裝結束。
之後執行：

• Run php artisan l5-swagger:publish 來進行初始化
• Run php artisan l5-swagger:generate 來生成環境變數到.env檔案中

現在可以看到在config目錄下有一個l5-swagger.php,裡面就是對應swagger的各個配置。

然後啟動專案，訪問你的網站地址/api/documentation就可以看到初始化介面了。

接下來在控制器中寫出一個SwaggerController，其中程式碼如下：

<?php

namespace App\Http\Controllers;

use Swagger\Annotations\Info;

/**
 * @Info(
 *     title="My title",
 *     version="v1.0.0"
 * )
 */
class SwaggerController extends Controller
{
    /**
     * 假設是專案中的一個API
     *
     * @SWG\Get(path="/swagger/my-data",
     *   tags={"project"},
     *   summary="拿一些神祕的資料",
     *   description="請求該介面需要先登入。",
     *   operationId="getMyData",
     *   produces={"application/json"},
     *   @SWG\Parameter(
     *     in="formData",
     *     name="reason",
     *     type="string",
     *     description="拿資料的理由",
     *     required=true,
     *   ),
     *   @SWG\Response(response="default", description="操作成功")
     * )
     */
    public function getMyData()
    {

    }
}

這是再訪問http://localhost/api/documentation，可以看到以下畫面：

現在，開始盡情使用Swagger吧。

附上Swagger-PHP的demo地址，可以參照其中的示例。
Swagger-PHP demo