如何在PHP中使用Swagger產生API文檔

隨著Web應用程式的不斷發展，API已經成為了現代Web應用開發的標準之一。然而，隨著API的數量和複雜度的增加，維護和文件化它們也變得越來越複雜。為了解決這個問題，Swagger應運而生。它是一種用於產生API文件的工具，可讓開發者更輕鬆地維護和文件化API，同時也提供了視覺化文件和其他各種功能。在本文中，我們將討論如何在PHP中使用Swagger產生API文件。

首先，我們需要安裝Swagger。 Swagger有很多版本和實作方式，但我們將在這裡使用Swagger-php，這是一個開源的PHP庫，可以輕鬆地將Swagger整合到PHP程式碼中。我們可以使用Composer在我們的專案中安裝Swagger-php：

composer require zircote/swagger-php

一旦我們安裝了Swagger-php，我們就可以開始為我們的API編寫Swagger規格。 Swagger規範是一個JSON或YAML文件，描述了API的所有細節，包括端點URL、請求和回應參數、資料模型和錯誤代碼。在Swagger-php中，我們可以使用PHP註解來寫規格。讓我們來看一個簡單的例子：

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */

在這個例子中，我們使用了@OA註解來寫Swagger規格。 @OA是Swagger-php庫中的命名空間，用來定義不同類型的Swagger元素，如Info、Get、Response和Parameter。我們可以使用@OAInfo註釋來描述API的基本訊息，如標題和版本。在@OAGet註解中，我們定義了兩個端點：/users和/users/{id}。我們描述了請求參數和回應，並指定了成功和錯誤的回應代碼。這只是一個很小的範例，但你可以透過使用其他@OA註解來寫更複雜的Swagger規範，甚至可以描述API的身份驗證和授權。

一旦我們編寫了我們的Swagger規範，我們就可以使用Swagger-php將其轉換為視覺化文件。為此，我們可以使用Swagger-ui，這是一個用來呈現Swagger規格的HTML、CSS和JavaScript函式庫。我們可以在PHP中使用Swagger-ui-php套件來整合Swagger-ui。我們可以使用Composer在我們的專案中安裝Swagger-ui-php：

composer require swagger-api/swagger-ui

一旦我們安裝了Swagger-ui-php，我們可以將Swagger-ui整合到我們的PHP應用程式中。我們可以在我們的HTML程式碼中加入以下行來載入Swagger-ui：

<link rel="stylesheet" type="text/css" href="/vendor/swagger-api/swagger-ui/dist/swagger-ui.css">
<div id="swagger-ui"></div>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-bundle.js"></script>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
<script>
  window.onload = function() {
    // 使用来自后端的Swagger JSON文件构造请求
    SwaggerUIBundle({
      url: "/api/swagger.json",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset // 用于额外的UI依赖
      ],
      layout: "StandaloneLayout"
    })
  }
</script>

在這個範例中，我們載入了Swagger-ui的CSS和JavaScript文件，並將其呈現在一個包含「swagger -ui”ID的DIV元素中。我們使用JavaScript程式碼來從後端載入Swagger JSON文件，並使用SwaggerUIBundle將其轉換為漂亮的文檔。

最後，為了讓Swagger-ui能夠載入我們的Swagger規範，我們需要在我們的應用程式中新增一個路由，用於返回Swagger JSON檔案。

use OpenApiAnnotations as OA;

$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

// 或者用这种方式

/**
 * @OAServer(url="http://localhost:8000")
 */

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */
$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

在這個例子中，我們使用OpenApi註解來寫Swagger規範，與之前的例子不同。我們還新增了一個路由來返回Swagger JSON檔。我們使用OpenApiscan PHP函數掃描我們的路由資料夾，並將API定義轉換為Swagger JSON對象，然後將其轉換為JSON字串並傳回給客戶端。

在本文中，我們了解如何使用Swagger-php和Swagger-ui在PHP中產生API文件。當我們的API數量和複雜度增加時，Swagger可以幫助我們更輕鬆地維護和文件化它們，同時提供可視化的API文件和其他各種功能。透過使用PHP註釋編寫Swagger規範，我們可以避免手動編寫文檔，並使我們的程式碼更加清晰且易於維護。

以上是如何在PHP中使用Swagger產生API文檔的詳細內容。更多資訊請關注PHP中文網其他相關文章！