L5-Swaggerを使ってOpenAPIドキュメントを作成する
こんにちは、中川です。今回は LaravelでOpenAPIのドキュメントを作成することができるL5-Swaggerを紹介したいと思います。
https://github.com/DarkaOnLine/L5-Swagger
■確認環境
- PHP 7.4.1
- Laravel 8.6
- L5-Swagger: 8.0.2
■インストール
Laravelプロジェクトは既にあるものとして、
まずは、l5-swaggerを追加します。
$ cd /path/to/project
$ composer.phar require "darkaonline/l5-swagger"■ドキュメント記入
そして、適当なPHPファイル(コントローラーなど)に、ドキュメント用のコメントを記入します。
＜?php
namespace App\Http\Controllers;
/**
* @OA\Info(
* version="1.0.0",
* title="L5-Swaggerサンプル",
* description="サンプル",
* )
*/
class HelloController extends Controller
{
/**
* @OA\Get(
* path="/hello",
* operationId="hello",
* tags={"タグ"},
* summary="ハロー",
* description="こんにちは",
* @OA\Response(
* response=200,
* description="成功",
* @OA\JsonContent(
* type="object",
* @OA\Property(
* property="message",
* type="string",
* description="メッセージ",
* example="Hello"
* )
* )
* )
* )
*/
public function index()
{
return ['message' => 'Hello'];
}
// ...省略...■ドキュメント生成
その後、以下のコマンドを実行すると、PHPソースコード内のOpenAPIド キュメントコメントを元にドキュメントファイルが生成されます。
php artisan l5-swagger:generate毎回コマンドで更新するのは面倒なので、以下の環境変数を.env追加します。
# .env
L5_SWAGGER_GENERATE_ALWAYS=trueこちらを設定しておけば、SwaggerUIをロードするたびに、自動でドキュメントが更新されます。
■ドキュメント確認
ブラウザでドキュメントのURL( /api/documentation )にアクセスすれば、SwaggerUIを確認することができます。
( 例: http://localhost:8000/api/documentation )
今回はL5-Swaggerの紹介をさせていただきました。このように、とても簡単にAPIドキュメントの生成・確認を行うことができますので、試してみてはいかがでしょうか。
