PHP で Swagger 仕様を使用して RESTful API に基づいた API ドキュメントを作成する方法

最新の Web アプリケーションでは、RESTful API はインターネット アプリケーションの重要な部分です。 RESTful API は HTTP プロトコルに基づくアーキテクチャ スタイルで、クライアントが HTTP リクエストを通じてサーバー上のリソースにアクセスできるようにします。アプリケーションを使いやすくするには、API ドキュメントを作成する必要があります。この記事では、Swagger 仕様を使用して RESTful API に基づいた API ドキュメントを作成する方法を紹介します。

Swagger は、開発者が機械可読な API ドキュメントを作成できるようにする一般的な API 仕様です。 Swagger 仕様では、エンドポイント、パラメータ、リクエスト本文、レスポンスなど、API のさまざまな側面が定義されています。また、開発者はセキュリティ、認証、バージョン管理などの API のさまざまな側面を定義できます。 Swagger を使用すると、開発者は事実上あらゆるテクノロジー スタックからクライアント側およびサーバー側のコードを自動的に生成できます。

Swagger を使用して API ドキュメントを作成する利点の一部を次に示します。

1. 読みやすく理解しやすい: Swagger は、読みやすく理解しやすい API ドキュメント形式を提供するため、開発者はAPI ユーザーは API のさまざまな側面をより簡単に理解できます。
2. ドキュメントの自動生成: Swagger は API ドキュメントを生成できるため、ドキュメントの作成時間を短縮できます。
3. 自動コード生成: Swagger は、API 仕様を使用してさまざまな言語でクライアント コードとサーバー コードを自動的に生成できるため、API の開発とテストが迅速化されます。

Swagger を使用して PHP で API ドキュメントを作成する方法の手順は次のとおりです:

1. Swagger を PHP プロジェクトに追加します

最初に, Swagger を PHP プロジェクトにインストールする必要があります。 Swagger は Composer を使用してインストールできます。

composer require zircote/swagger-php

2. API 仕様の定義

Swagger をプロジェクトに追加したら、次のステップは API を定義することです。仕様。アノテーション構文を使用して、PHP コードで Swagger 仕様を定義できます。例を次に示します。

/**

• @OAGet(
• path="/articles",
• summary="記事のリストを取得",
• @OAResponse(応答="200", description="記事一覧")
• )
  */

この例では、グループ記事を返す「/articles」という名前の GET リクエストを定義します。 @OAGet アノテーションでは、エンドポイントとサマリーを指定します。 @OAResponse アノテーションでは、200 レスポンスと、そのレスポンスを説明する文字列を定義します。

API 仕様のさまざまな側面を次の方法で指定できます。

1. @OAGet: HTTP リクエスト タイプの GET のエンドポイントを定義します。
2. path: 終点のパスを指定します。
3. summary: 終端点について簡単に説明します。
4. @OAResponse: レスポンスを定義します。
5. response: レスポンスコードを指定します。
6. description: 応答の説明を提供します。
7. API ドキュメントの生成

API 仕様を定義したら、次のステップはそれをフォーマットされたドキュメントに変換することです。 Swagger UI を使用して API ドキュメントを表示できます。 Swagger UI は、ユーザーが API エンドポイントをテストし、API 仕様を表示できる対話型 API ドキュメントを備えたツールです。

Swagger UI ドキュメントを生成するには、Swagger-php パッケージによって提供される Swagger 静的ファイルを使用する必要があります。 Swagger UI ファイルは、次のコマンドを使用してプロジェクトにコピーできます:

vendor/bin/openapi --output public/swagger.json app/Http/Controllers

このコマンドでは、次のコマンドを保存します。パブリック フォルダーのアプリケーション ルート フォルダーにある swagger.json ファイル。プロジェクトのニーズに応じて、独自の静的ファイルを生成できます。

4. API ドキュメントへのアクセス

Swagger UI ドキュメントを生成した後、ブラウザーを通じてアクセスできます。 Swagger UI にアクセスするときは、Swagger JSON ファイルへのパスを指定する必要があります。サンプル URL は次のとおりです:

http://localhost/swaggers/public/index.html?url=http://localhost/swaggers/public/swagger.json

この URL 内では、Swagger JSON ファイルへのパスを指定します。

結論

この記事では、Swagger 仕様を使用して RESTful API に基づいた API ドキュメントを作成する方法を紹介します。 Swagger の利点と、Swagger を使用して API 仕様を記述し、PHP プロジェクトで API ドキュメントを生成する手順について説明しました。これらの手順に従うことで、読みやすく理解しやすい API ドキュメントをより簡単に作成できるようになり、API の開発とテストが迅速化されます。

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