Lumenマイクロサービス生成Swaggerドキュメント

phperとしてLumenフレームワークを使用してマイクロサービスを開発する場合、APIドキュメントの書き込みは常に少なくありません.比較的ポピュラーな方法はswaggerを使用してAPIドキュメントを書くことですが、Java言語のオリジナルサポートannotationとは異なり、phpはswaggerドキュメントを単独で維持するか、注釈にannotationsを追加して類似の機能を実現するしかありません.しかし,注釈にSwagger注釈を書くのは非常に苦痛で,コードヒントがなく,フォーマットされていない.
この文書では、phpstormのannotationsプラグインを使用して、Lumenマイクロサービスプロジェクトを開発する際に(Laravelプロジェクトは他のphpプロジェクトと似ています)コードで注釈を使用してswaggerドキュメントを作成する方法を説明します.
本文は引き続き修正して更新して、最新の内容は私のGITHUBの上のプログラム猿の成長計画プロジェクトを参考にしてください、スターを歓迎して、もっとすばらしい内容はfollow meをお願いします.
フレーム構成
現在の最新のLumen 5.7を用いて実証した.プレゼンテーションコードはgithubに置いてありますが、興味のある方は参考にしてください

https://github.com/mylxsw/lumen-swagger-demo

インストール依存
Lumenプロジェクトでは、まずcomposerを使用してSwaggerLumeプロジェクト依存をインストールする必要があります.

composer require darkaonline/swagger-lume

プロジェクト構成bootstrap/app.phpファイルでは、次の構成のコメント(約26行)を削除し、Facadesサポートを有効にします.

$app->withFacades();

SwaggerLumeプロジェクトのプロファイルを有効にし、Register Container Bindingsセクションの前に追加

$app->configure('swagger-lume');

そして、Register Service Providers部に、SwaggerLumeのServiceProviderを登録する

$app->register(\SwaggerLume\ServiceProvider::class);

プロジェクトのルートディレクトリで、実行コマンドphp artisan swagger-lume:publishはswagger関連の構成を発行します.
この命令を実行した後、主に以下のいくつかの変更を体現する.

config/ディレクトリには、プロジェクトのプロファイルswagger-lume.php

が追加する.

resources/views/vendorディレクトリには、生成されたAPIドキュメント

をプレビューするためのswagger-lume/index.blade.phpビューファイルが生成する.
プロファイルから次の重要な情報を取得できます.

api.title生成APIドキュメント表示タイトル

routes.api生成されたAPIドキュメントUIにアクセスするためのルーティングアドレスのデフォルトは/api/documentation

である.

routes.docsは、生成されたAPIドキュメントの原文、jsonフォーマットにアクセスするために使用され、デフォルトのルーティングアドレスは/docs

である.

paths.docsとpaths.docs_jsonコンビネーションはapi-docs.jsonファイルのアドレスを生成し、デフォルトはstorage/api-docs/api-docs.jsonであり、php artisan swagger-lume:generateコマンドを実行すると、そのファイル

が生成する.
構文の自動ヒント
純粋な手書きswagger注釈は間違いなく、間違いやすいので、ドキュメントの参考文法を繰り返し見る必要があります.そのため、注釈の注釈文法を自動的に提示できるプラグインをインストールする必要があります.私たちがよく使うIDEはphpstormです.phpstormではPHP annotationプラグインをインストールする必要があります.
プラグインをインストールした後、Swaggerドキュメントを書くときに、コード自動プロンプト機能があります.
文書を書く
Swaggerドキュメントには、特定のAPIに関係のない多くの情報が含まれています.app/Http/Controllersには、ビジネスロジックを実装せず、共通のドキュメント情報を配置するためにのみ使用されるSwaggerControllerが作成されています.

次に、ビジネスロジックコントローラでAPIを書くことができます.

name   = $request->input('name');
        $resp->id     = 123;
        $resp->age    = $request->input('age');
        $resp->gender = $request->input('gender');

        $prop1        = new DemoAdditionalProperty();
        $prop1->key   = "foo";
        $prop1->value = "bar";

        $prop2        = new DemoAdditionalProperty();
        $prop2->key   = "foo2";
        $prop2->value = "bar2";

        $resp->properties = [$prop1, $prop2];

        return $resp;
    }
}

ここでは、応答結果において、SwaggerControllerで定義されているApiResponseを参照し、定義されていないExampleRespオブジェクトを参照し、app\Http\Responsesディレクトリ(自分で作成したディレクトリ)でExampleRespオブジェクトを実現し、応答オブジェクトをこのディレクトリに配置することができます.

オブジェクトを返して他のオブジェクトを参照

ドキュメントの生成
次のコマンドを実行すると、ドキュメントを生成できます.生成されたドキュメントはstorage/api-docs/api-docs.jsonです.

php artisan swagger-lume:generate

ドキュメントのプレビュー
ブラウザアクセスhttp://アクセスアドレス/docsを開くと、次のように表示されます.
http://アクセスアドレス/api/documentationにアクセスすると、
インタフェース詳細展開
その他
この文書では、Lumenプロジェクトでコード注釈を使用してSwaggerドキュメントを自動的に生成し、phpstormのコードヒント機能に合わせる方法を簡単に説明しますが、これらを習得するにはまだ十分ではありません.Swagger-phpプロジェクトのExamplesカタログには多くの使用例が含まれています.参考にしてください.
チームプロジェクトではswaggerドキュメントが使用されていますが、ドキュメントを管理する場所が必要ですね.ここではWizardプロジェクトをお勧めします.このプロジェクトはチームコラボレーション用のドキュメント管理ツールで、MarkdownドキュメントとSwaggerドキュメントをサポートしています.興味があるなら試してみてください.