PHP で Swagger を使用して API ドキュメントを生成する方法

Web アプリケーションの継続的な開発により、API は最新の Web アプリケーション開発の標準の 1 つになりました。ただし、API の数と複雑さが増加するにつれて、API の保守と文書化はますます複雑になります。この問題を解決するために、Swagger が誕生しました。これは API ドキュメントを生成するためのツールであり、開発者が API の保守とドキュメント化を容易にすると同時に、視覚的なドキュメントやその他のさまざまな機能も提供します。この記事では、PHP で Swagger を使用して API ドキュメントを生成する方法について説明します。

まず、Swagger をインストールする必要があります。 Swagger には多くのバージョンと実装がありますが、ここでは Swagger-php を使用します。これは、Swagger を PHP コードに簡単に統合できるオープン ソースの PHP ライブラリです。 Composer を使用してプロジェクトに Swagger-php をインストールできます。

composer require zircote/swagger-php

Swagger-php をインストールしたら、API の Swagger 仕様の作成を開始できます。 Swagger 仕様は、エンドポイント URL、リクエストおよびレスポンス パラメータ、データ モデル、エラー コードなど、API の詳細をすべて記述する JSON または YAML ファイルです。 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 は、Info、Get、Response、Parameter などのさまざまなタイプの Swagger 要素を定義するために使用される Swagger-php ライブラリ内の名前空間です。 @OAInfo アノテーションを使用して、タイトルやバージョンなどの API の基本情報を記述することができます。 @OAGet アノテーションでは、/users と /users/{id} という 2 つのエンドポイントを定義します。リクエストパラメータとレスポンスを記述し、成功とエラーのレスポンスコードを指定します。これはほんの小さな例ですが、他の @OA アノテーションを使用してより複雑な Swagger 仕様を記述したり、API の認証と認可を記述することもできます。

Swagger 仕様を作成したら、Swagger-php を使用してそれをビジュアル ドキュメントに変換できます。このために、Swagger 仕様をレンダリングするための HTML、CSS、および JavaScript ライブラリである Swagger-ui を使用できます。 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 ファイルをロードし、それらを DIV の -ui" ID でレンダリングします。要素。 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 ドキュメントやその他のさまざまな機能を提供しながら、API の維持と文書化がより簡単になります。 PHP アノテーションを使用して Swagger 仕様を記述することにより、ドキュメントを手動で作成する必要がなくなり、コードがより明確になり、保守が容易になります。

以上がPHP で Swagger を使用して API ドキュメントを生成する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。