テクノロジー
ノウハウ・TIPS
2020年9月29日
L5-Swaggerを使ってOpenAPIドキュメントを作成する
nakagawayoshiki
こんにち は、中川です。今回は 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ドキュメントの生成・確認を行うことができますので、試してみてはいかがでしょうか。
