福岡拠点の野田です。
OpenAPI(Swagger)の仕様書を使っていますか？
PHPでは、アノテーションでOpenAPIを定義できるSwagger-PHPというものがあります。使うためには以下を実行します。
|
1 |
[crayon-673ef34e660ea713180167 ]composer require --dev zircote/swagger-php |
対象のコントローラーを指定するとアノテーションで記載したコメントがAPI仕様書になるという素晴らしいライブラリです。swagger.ymlの書き出し方は、以下。
|
1 |
[crayon-673ef34e660ef292547061 ]vendor/zircote/swagger-php/bin/openapi app/Http/Controllers/Api/*Controller.php -o swagger.yml |
ここで少しはまりどころがあります。
OA\Infoを定義したクラスには必ずOA\GetやOA\PutといったAPIをセットで定義しなければなりません。それをしないと以下のエラーで怒られます。
|
1 |
[crayon-673ef34e660f3262173576 ]Required @OA\PathItem() not found |
ちょー分かりにくいエラーなので、私もはまりました。そんなときは汎用エラーレスポンスでも定義してしのぎましょう。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
[crayon-673ef34e660f7612828578 ] /** * @OA\Put( * path="/api/*", * tags={"ErrorCommon"}, * description="APIエラー共通", * @OA\Response( * response="default", * description="APIエラー時の返却データ", * @OA\JsonContent( * @OA\Property(property="error", type="integer", description="エラー値(0:正常/1:エラー)"), * @OA\Property(property="errorId", type="string", description="エラーID"), * @OA\Property(property="code", type="string", description="エラーコード"), * @OA\Property(property="message", type="string", description="エラーメッセージ"), * ) * ) * ), */ private function error() { throw new UnsupportedOperationException(); } |
これはライブラリ側でなんとかしてほしかったところではありますが、めげずにswaggerを使っていきましょう。
それでは、また！