Swagger は、開発者が API インターフェイスを簡単に作成、設計、展開できるようにする人気の API ドキュメント生成ツールです。この記事では、Swagger を使用して ThinkPHP6 で API ドキュメントを生成し、Swagger-UI を使用して API インターフェイスを表示およびテストする方法を紹介します。
ステップ 1: Swagger-UI および Swagger-Annotations のインストール
ThinkPHP6 で Swagger を使用するには、Swagger-UI および Swagger-Annotations ライブラリをインストールする必要があります。これらは Composer を通じてインストールできます。プロジェクトのルート ディレクトリで次のコマンドを実行するだけです:
composer require zircote/swagger-php composer require swagger-api/swagger-ui
ステップ 2: コントローラーに Swagger-Annotations を追加する
コントローラーで Swagger を使用するには、以下が必要です。コントローラーのアノテーションに Swagger-Annotations を追加します。たとえば、サンプル コントローラーと、その中で Swagger-Annotations を使用したサンプル コードを次に示します。
<?php namespace appcontroller; use thinknnotationouteGroup; use thinknnotationouteMiddleware; use thinkController; /** * @Group("/api/v1") * @Middleware(class="ppmiddlewareToken") */ class UserController extends Controller { /** * 用户列表接口 * * @SwaggerGet( * path="/user/list", * summary="获取用户列表", * tags={"User"}, * @SwaggerResponse(response="200", description="OK"), * @SwaggerResponse(response="401", description="Unauthorized"), * ) */ public function index() { // 代码逻辑 } }
上記のコードでは、@Group
アノテーションを使用して、コントローラーの場合は、 @Middleware
アノテーションを使用してコントローラー ミドルウェアを指定します。 index
メソッドでは、@SwaggerGet
アノテーションを使用して、リクエスト パス、インターフェイスの概要、ラベルと応答の情報など、GET リクエストに必要な情報を指定します。
ステップ 3: Swagger ドキュメントの生成
Swagger ドキュメントを生成するには、Swagger ドキュメントを手動で作成する、Swagger エディターを使用する、Swagger ジェネレーターを使用するなど、さまざまな方法があります。ここでは、Swagger-Annotations が提供するコマンド ライン ツールを使用して、Swagger ドキュメントを自動的に生成します。
プロジェクトのルート ディレクトリに次のコマンドを入力します。
php think swagger output json > swagger.json
これにより、Swagger-Annotations の output
コマンドを使用して、Swagger ドキュメントが JSON ファイルに出力されます。
ステップ 4: Swagger-UI を使用して API インターフェイスを表示およびテストする
Swagger ドキュメントを生成したので、それを表示する必要があります。 Swagger-UI を使用して API インターフェイスを表示およびテストできます。
プロジェクト public/swagger
に新しいディレクトリを作成し、Swagger-UI 公式 Web サイトからダウンロードしたすべての静的ファイルをこのディレクトリにコピーします。次に、index.html
ファイル内の url
変数を変更して、生成したばかりの Swagger ドキュメントを指すようにする必要があります。
var url = "../swagger.json";
最後に、ブラウザで http://localhost/swagger
を開き、Swagger-UI インターフェイスを表示します。ここでは、API インターフェイスのドキュメントを参照し、API インターフェイスをテストし、API インターフェイスのリクエストと応答の情報を表示できます。
概要:
上記は、Swagger を使用して ThinkPHP6 で API ドキュメントを生成する手順のすべてです。 Swagger を使用すると、開発者は API インターフェイスのドキュメント化、テスト、展開をより簡単に完了でき、開発効率が向上し、開発コストが削減されます。ただし、悪意のある攻撃やデータ漏洩を防ぐために、API インターフェイスのセキュリティの保護にも注意を払う必要があります。
以上がThinkPHP6 で Swagger を使用する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。