Laravel 開発: Laravel Swagger を使用して API ドキュメントを生成するにはどうすればよいですか?

Laravel 開発: Laravel Swagger を使用して API ドキュメントを生成するにはどうすればよいですか?

Web アプリケーションを開発する場合、API ドキュメントの操作は面倒ですが不可欠な作業となることがよくあります。 Swagger を使用して、API ドキュメントを自動的に生成および視覚化します。 Laravel 開発では、Laravel Swagger 拡張パッケージを使用して、Swagger API ドキュメントを簡単に生成できます。この記事では、Laravel で Laravel Swagger を使用する方法について説明します。

1. Laravel Swagger のインストール

Composer を使用して Laravel Swagger 拡張パッケージをインストールします:

composer require darkaonline/l5-swagger

2. Laravel Swagger の構成

Laravel Swagger は Swagger UI に依存しているため、Swagger UI のリソースを Laravel のパブリック ディレクトリに公開する必要があります。次のコマンドを使用して公開を完了します:

php artisan vendor:publish --provider "L5SwaggerL5SwaggerServiceProvider"

公開コマンドを実行すると、次のようになります。 public/ では、vendor ディレクトリの下に swagger-ui ディレクトリがあり、このディレクトリには Swagger UI のすべてのリソースが含まれています。

次に、Laravel の設定ファイル config/app.php に次の行を追加します。

'providers' => [
    ...
    L5SwaggerL5SwaggerServiceProvider::class,
],

'aliases' => [
    ...
    'Swagger' => L5SwaggerFacadesL5Swagger::class,
],

3. Swagger コメントを追加します
推論される API 形式が存在しないことを Laravel Swagger に伝えるには、コードに Swagger アノテーションを追加する必要があります。これらのアノテーションにより、Laravel Swagger は API を自動的に解析し、対応するドキュメントを生成できます。

/**
 * @OAGet(
 *      path="/users",
 *      operationId="getUsersList",
 *      tags={"Users"},
 *      summary="Get list of registered users",
 *      description="Returns list of users",
 *      @OAResponse(response="200", description="successful operation"),
 *      @OAResponse(response=401, description="Unauthorized"),
 *      @OAResponse(response=403, description="Forbidden"),
 *      @OAResponse(response=404, description="Not Found"),
 *      @OAResponse(response=500, description="Internal Server Error")
 *     )
 */

上の例では、

@OAGet

アノテーションを使用して、これが GET リクエストであることを示しています。 path アノテーションは API へのパスを定義します。 tags および summary コメントは、Swagger ドキュメント内の概要とタグを表示するために使用されます。最後に、@OAResponse アノテーションは、考えられる応答状態を例示しています。

Laravel で Swagger ドキュメントを表示する

これまでの手順をすべて完了したら、次の URL を使用して Laravel Swagger ドキュメントを表示できます:

http://your-app.dev/api/documentation

(Laravel 5.4 以降を使用している場合は、

.dev

を定義する必要はありません。代わりに .test または他のローカル ドメイン名を使用してください。) Laravel の開発サーバーを起動し、上記の URL にアクセスすると、ブラウザーで自動生成された Swagger ドキュメントが表示されるはずです。

Swagger ドキュメントでは、定義された API を表示し、API に追加された Swagger アノテーションに基づいて API をテストし、考えられる応答状態を表示できます。

概要

この記事では、Laravel Swagger 拡張パッケージを使用して Swagger API ドキュメントを簡単に生成する方法を学びました。まず、Laravel Swagger をインストールし、次に Swagger を起動して、Swagger アノテーションを API に追加しました。最後に、Laravel Swagger によって生成されたドキュメントを確認しました。

Laravel Swagger を使用すると、API ドキュメントを手動で作成する負担が大幅に軽減され、発生する可能性のあるエラーや不一致を回避できます。 Swagger UI を使用すると、開発者にとって使いやすいインターフェイスを提供しながら、API をより簡単に表示およびテストできるようになります。

以上がLaravel 開発: Laravel Swagger を使用して API ドキュメントを生成するにはどうすればよいですか?の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。