將 Swagger UI 與 Codeigniter4 集成

Swagger 是一種廣泛使用的 API 文件和測試工具，可與 Laravel、Spring Boot、CodeIgniter 和 ExpressJS 等流行的 Web 框架無縫整合。在本文中，我們將重點介紹 Swagger 與 CodeIgniter 的整合。

安裝依賴項：

composer require zircote/swagger-php doctrine/annotations

下載 SwaggerUI .zip 或 SwaggerUI GitHub 儲存庫：

• 下載連結：SwaggerUI 最新版本 下載最適合您要求的 Swagger UI 版本。

編寫控制器：

要為 Swagger UI 產生 swagger.json 文件，我們必須建立一個控制器。根據您的選擇將控制器命名為 SwaggerDocGenerator.php。在控制器中，我們必須使用 zircote/swagger-php 中的 OpenApiGenerator 將所有 @OA 語法轉換為 JSON。

<?php
namespace App\Controllers;

use OpenApi\Generator;

class SwaggerDocGenerator extends BaseController
{
    /**
     * Generate OpenAPI documentation for the API ...
     * @return string
     */
    public function generate(): string
    {
        // Specify the path where your API controllers are located
        $openapi = Generator::scan([APPPATH . 'Controllers']);

        $swaggerContent = $openapi->toJson();

        // Save the generated OpenAPI content to a file
        $filePath = FCPATH . 'swagger_ui/swagger.json';
        file_put_contents($filePath, $swaggerContent);

        return $swaggerContent;
    }

    /**
     * Render the SwaggerUI ...
     * @return string
     */
    public function index()
    {
        return view('swagger_docs/index');
    }
}

?>

建立路線：

透過在 Config/Routes.php 上建立路由，我們將能夠產生預期的 sawgger.json 檔案。

// Create API documentation ...
$routes->get('api/v1/docs/generate', 'SwaggerDocGenerator::generate');
$routes->get('api/v1/docs/ui', 'SwaggerDocGenerator::index');

渲染 Swagger UI：

有多種方法可以將 swagger.json 檔案渲染到 SwaggerUI 中：

• 將 swagger.json 檔案匯入 POSTMAN。
• 使用 SwaggerUI 和您自己的視圖來渲染 SwaggerUI。
• 在前端應用程式中設定環境，以透過請求後端 API 取得 swagger.json 檔案來呈現 SwaggerUI。

在這裡，我們將看到前兩種方式。我們將在另一篇文章中討論第三種方式。

將 swagger.json 檔案匯入到 POSTMAN 中：

• 複製 swagger.json。
• 打開郵差。
• 點選左上角的導入按鈕。
• 貼上複製的 swagger.json。

將 SwaggerUI 與您自己的視圖一起使用來呈現 SwaggerUI：

• 在視圖資料夾 app/Views/swagger_docs/index.php 中建立一個 .php 檔案來渲染 SwaggerUI。
• 將下載的 SwaggerUI .zip 檔案解壓縮到 public/swagger_ui/ 資料夾中。

composer require zircote/swagger-php doctrine/annotations

筆記：

• 確保執行 php Sparkserve 命令來執行 Codeigniter4 應用程式。
• 每次變更 OpenAPI 文件語法時，都必須執行 http://localhost:8080/api/v1/docs/generate URL 來產生更新的 swagger.json 檔案。
• 確保使用 swagger.json 檔案的更新 URL 更新 swagger-initializer.js 檔案。

結論：

在本文中，我們探索了將 Swagger 與 CodeIgniter 4 集成，產生 swagger.json 文件，在 Swagger UI 中渲染它，並將其導入 Postman。我們也示範如何在自訂檢視中呈現 Swagger UI。然而，手動產生 swagger.json 檔案並更新 swagger-initializer.js 檔案中的 URL 並不理想。

在下一篇文章中，我將示範使用自訂 CLI 命令自動化此流程，並旨在為此目的開發一個開源套件。歡迎在評論部分分享您的建議或問題。

以上是將 Swagger UI 與 Codeigniter4 集成的詳細內容。更多資訊請關注PHP中文網其他相關文章！