Laravel API Documentation Generator 拡張パッケージを使用して、プロジェクトの API ドキュメントを自動的に生成します

1. 導入とインストール

Laravel API Documentation Generator 拡張パッケージは、Laravel アプリケーションのルーティングに基づいてプロジェクト API ドキュメントを自動的に生成できます。

この拡張機能パッケージをインストールするには Composer を使用します:

$ composer require mpociot/laravel-apidoc-generator

インストールが完了したら、config/app.php にサービス プロバイダーを登録する必要があります:

Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

2. 使用する

基本的な例

その方法を示してみましょうこの拡張機能パッケージを使用します。 プロジェクトの API ドキュメントを自動生成する原理は、routes.php をスキャンして、指定されたルートに対応する API ドキュメントを生成することです。 たとえば、ルーティング ファイルは次のようにルートを定義します:

Route::get('api/v1/index', 'ApiController@index');

このルートに対応するコントローラー メソッド。

/** * API首页 * * 欢迎来到Laravel学院，Laravel学院致力于提供优质Laravel中文学习资源 * */public function index(){}

Laravel API ジェネレーターは、アクション メソッドのアノテーションを通じて API に対応する記述情報を生成することに注意してください。拡張機能パッケージによって提供される api:generate コマンドを使用して、API ドキュメント生成を実装します。

php artisan api:generate --routePrefix=api/v1/*

このコマンドは、api/v1/* に一致するルーティング ルールをスキャンし、対応するコントローラー メソッドの API ドキュメントを生成することを意味します。 public docs ディレクトリと対応するファイルがディレクトリ内に生成されます。ブラウザで http://blog.dev/docs/index.html (私のドメイン名は blog.dev) を通じて API ドキュメントを表示します。応答データの例

上記は最も単純な例です。ほとんどの場合、アクションは HTTP 応答を返します。この場合、API ドキュメントはどのように表示されるでしょうか。

ルーティング ファイル Routes.php で次のようにルートを定義します:

Route::get('api/v1/test', 'ApiController@test');

対応するコントローラー メソッドは次のように定義されます:

/** * API响应测试 * * 这是一个API响应测试页面 * */public function test(){    return new Response('Laravel学院,优质Laravel中文学习资源平台');}

アクションで文字列情報を含むレスポンスを返すだけで、API を生成する必要があります。このメソッドのドキュメントを参照するには、 api:generate コマンドを実行する必要があります:

php artisan api:generate --routePrefix=api/v1/*

操作が完了したら、http://blog.dev/docs/index.html に再度アクセスすると、API 応答テスト情報を確認できます。

右下隅で、応答データ情報を確認できます。

API を呼び出すためにユーザーを認証する必要がある場合は、API ドキュメントを生成するときに --actAsUser オプションを追加してユーザー ID を指定できます。

php artisan api:generate --routePrefix=api/v1/* --actAsUserId=1

パラメーター付き API

より複雑な例を見てみましょう。 API に POST リクエストを送信する際、パラメータが含まれます。このときパラメータ付きの API ドキュメント情報を生成するにはどうすればよいですか?これは非常に簡単で、通常のロジックに従ってから api:generate コマンドを実行するだけです。

ポストリクエストルートを次のように定義します:

Route::post('api/v1/params', 'ApiController@params');

コントローラーメソッドを定義する前に、まず次のコマンドを使用してリクエストクラスを生成します:

php artisan make:request TestRequest

これにより、app/Http/Requests ディレクトリに新しい TestRequest クラスが生成されます。このクラスのルール メソッドを次のように編集します:

public function rules(){    return [        'title' => 'required|max:255',        'body' => 'required',        'type' => 'in:foo,bar',        'thumbnail' => 'required_if:type,foo|image',    ];}

次に、コントローラーで対応するメソッドを定義します:

/** * API请求参数 * * 测试API请求参数 * * @param Requests\TestRequest $request */public function params(Requests\TestRequest $request){    }

コントローラー メソッドで依存関係注入を通じて作成したばかりの TestRequest クラスを渡します。

最後に、api:generate コマンドを使用して新しい API ドキュメントを段階的に生成します。

php artisan api:generate --routePrefix=api/v1/*

ブラウザで http://blog.dev/docs/index.html にアクセスすると、パラメータを含む API が表示されます。ページのドキュメント情報:

その他の用途

デフォルトの API ドキュメント テンプレートが醜すぎると感じる場合、拡張パックには、デフォルトの API ドキュメント テンプレートを変更するための api:update コマンドも用意されています。その操作プロセスは、まず次のとおりです。 Index.md ファイル (public/docs/source/index.md にあります) を変更し、変更後、次のコマンドを使用して変更を保存します:

php artisan api:update

この関数は非常に単純なので、ここでは説明しません。詳細については、拡張機能の GitHub プロジェクトを参照してください: https://github.com/mpociot/laravel-apidoc-generator/。