利用ThinkPHP6實現API文件自動生成

隨著API的應用越來越廣泛，自動產生API文件成為了一個不可或缺的工具。本文將介紹如何利用ThinkPHP6框架自動產生API文件。

一、ThinkPHP6框架介紹

ThinkPHP6是一個使用PHP語言開發的高效、簡單、方便、靈活的開源框架。它採用了物件導向的開發模式，支援MVC（模型-視圖-控制器）架構，具有路由、快取、驗證、模板引擎等強大功能。

二、安裝Swagger UI

Swagger是一種API文檔自動產生工具，它能夠自動產生API的文檔，並且提供了一個Web介面來示範API的執行結果。在使用ThinkPHP6來實作API文件自動產生時，我們需要先安裝Swagger。

我們可以透過Composer工具來安裝Swagger。在命令列中輸入：

composer require zircote/swagger-php

安裝完成後，在專案的根目錄下建立Swagger設定文件，命名為swagger.php：

<?php
return [
    'swagger' => [
        'api' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'paths' => [
            APP_PATH . '/',
        ],
        'exclude' => [
        ],
        'swagger-ui' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'securityDefinitions' => [
        ],
    ],
];

三、定義API文件註解

為了讓Swagger能夠自動辨識並產生API文檔，我們需要在程式碼中加入對應的註解。 ThinkPHP6提供了一個自訂的註釋格式，用於定義API文件。

在控制器中定義API文件註解：

<?php
declare(strict_types=1);

namespace appcontroller;

class Example
{
    /**
     * @OAGet(
     *      path="/example/index",
     *      operationId="exampleIndex",
     *      tags={"Example"},
     *      summary="示例接口",
     *      description="这是一个示例接口",
     *      @OAResponse(
     *          response=200,
     *          description="操作成功",
     *      ),
     *      @OAResponse(
     *          response=401,
     *          description="未授权",
     *      ),
     *      security={
     *          {"Bearer": {}}
     *      }
     * )
     */
    public function index()
    {
        //接口代码
    }
}

上面的程式碼中，@OA開頭的註解標籤被解析為Swagger的規範格式。其中，@OAGet定義了API的請求方式為Get方法；path定義了API的路徑；operationId定義了操作的id；tags定義了API所屬的標籤；summary定義了API的概述；description定義了API的詳細描述;@OAResponse定義了API的回應結果及狀態碼；security定義了API的存取權。

四、產生API文件

在定義好API文件註解後，我們可以使用Swagger來產生API文件。在命令列中輸入以下命令：

php think swagger:export --output public/swagger.json

該指令會將API文件儲存到public目錄下的swagger.json檔案中。

五、存取API文件

使用Swagger UI來展示API文件。我們可以將Swagger UI專案部署到Web伺服器中，或在本地運行。

在本地運行時，我們可以使用下面的命令快速啟動一個Swagger UI服務：

docker run --rm -p 8080:8080 -e SWAGGER_JSON=/data/swagger.json -v /path/to/swagger.json:/data/swagger.json swaggerapi/swagger-ui

其中，/path/to/swagger.json是swagger.json檔案的絕對路徑。

在瀏覽器中造訪http://localhost:8080即可查看API文件。

六、總結

本文介紹如何利用ThinkPHP6框架和Swagger自動產生API文件。自動產生API文件可以提高開發效率，降低維護成本。透過本文的介紹，相信讀者已經能夠熟練地運用ThinkPHP6框架和Swagger來實現API文檔的自動生成。

以上是利用ThinkPHP6實現API文件自動生成的詳細內容。更多資訊請關注PHP中文網其他相關文章！