vyuldashev/laravel-openapi

参考

Laravelで作る、OpenAPIによるAPIリファレンス自動生成 with GitLab CI

手順

1. laravelのお作法通りControllerを作成＆ api.php にroute定義
2. リクエスト定義

• GETの場合は Parameters生成
• POSTの場合は Request Bodies 生成

3. レスポンス定義

• Responses
• レスポンスの中身はSchemaクラスを作成

4. ターミナルで php artisan openapi:generate を実行すると、jsonが出力される

メモ

• 出力されたjsonを https://editor.swagger.io/ に貼り付け、OpenAPIのドキュメントが正しく出力されているか確認できる
• Schemaとは
  • https://zenn.dev/manabu/articles/35ea2ddfe2df3a#スキーマってそもそも何？

  レスポンスの返却内容の定義

• https://qiita.com/miriwo/items/fee0ffb12737448691e4#オブジェクトの中の配列のの中にオブジェクト

Swagger導入

swagger-ui

npmやdockerコンテナなどある
https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md

l5-swagger

laravel用のswaggerライブラリ
今回はこちらを導入してみる
参考: https://zenn.dev/nicopin/articles/c6667934422712

l5-swagger導入手順

1. composer require "darkaonline/l5-swagger" 実行
2. AppServideProvider.php の register() メソッドに以下を設定

$this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);

3. app/Http/Controllers/Controller.php クラス名の上に、以下のdocを設定

/**
 * @OA\Info(
 *     version="1.0.0",
 *     title="Your System Name",
 *     description="Sample system"
 *
 * )
 */

4. API定義したいControllerのメソッドにdoc追記

• 参考: https://github.com/zircote/swagger-php/blob/master/Examples/petstore-3.0/Controllers/User.php

5. php artisan l5-swagger:generate 実行
6. ブラウザで 起動しているサーバーの api/documentation にアクセス

エラーと対処方法

OpenAPIの記法に関するライブラリ

vyuldashev/laravel-openapi

• laravel用のOpenAPI定義書生成ライブラリ
• https://zenn.dev/link/comments/f3b903bf0cc962 導入手順記載済み

Swagger-PHP

• PHPのソースコードからAPIのメタデータを生成
• l5-swaggerにラッパーされている
• 記法が2つある
  • Attributes
    • PHPのattributeの記法でメタデータを書ける
  • Annotations

derline/openapi-php-attributes

• PHP attributeをもとにOpenAPI定義書を生成するライブラリ

laravel-openapi-validator