laravel環境にswaggerを入れる

未分類


laravelでswaggerを入れる場合にパッケージ入れるとしたら

  • darkaonline/l5-swagger
  • zircote/swagger-php

の2択になりそうです。

両方ともつかい勝手を読んでみたのですが「darkaonline/l5-swagger」の方がインストールが簡単、jsonの吐き出しを.envに書き足すと更新してくれる。の2点で良さそうです。

darkaonline/l5-swaggerを使ってみる。

どのように使うかと言うと前提としてコントローラーにjsonファイルを書き出し元となる記述を書くとjsonを吐き出すと言う仕様があります。

まずはインストールから、docker環境の場合でメモリーオーバーになってしまう場合は下記コマンドで実行

docker-compose exec コンテナ名 bash -c "COMPOSER_MEMORY_LIMIT=-1 composer require darkaonline/l5-swagger"

インストールが完了しましたら。swaggerの表題になる設定をapp\swagger.phpに設定します。
例としては下記の通り、コメントアウトされてますがOKです。

<?php

/**
 * @OA\Info(
 *  title="API Example",
 *  description="description",
 *  version="1.0.0",
 * )
 *
 *  @OA\Server(
 *   description="OpenApi host",
 *   url="http://localhost:3000"
 * )
 */

次にコントローラーに記述の追加。

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;

class UserApiController extends Controller
{
    /*下記を追加*/
    /**
     * @OA\Get(
     *     path="/user",
     *     operationId="user",
     *     tags={"user"},
     *     summary="ユーザー",
     *     description="user用",
     *     @OA\Response(
     *         response=200,
     *         description="成功",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(
     *                 property="message",
     *                 type="string",
     *                 description="メッセージ",
     *                 example="massage"
     *             )
     *         )
     *     )
     * )
     */

    public function getUser()
    {

postの場合

引用
https://qiita.com/horikeso/items/34ad3c91a6864e868d34

/**
 * @OA\Post(
 *   path="/api/example/{id}",
 *   summary="具体例が無かったので寄せ集めてみた",
 *   @OA\RequestBody(
 *     required=true,
 *     @OA\JsonContent(
 *       type="object",
 *       required={"number", "text"},
 *       @OA\Property(
 *         property="number",
 *         type="integer",
 *         format="int32",
 *         example=1,
 *         description="リクエストボディのjsonのプロパティの例"
 *       ),
 *       @OA\Property(
 *         property="text",
 *         type="string",
 *         example="text",
 *         description="リクエストボディのjsonのプロパティの例"
 *       )
 *     )
 *   ),
 *   @OA\Parameter(
 *     name="id",
 *     in="path",
 *     required=true,
 *     description="パスからのパラメータ例",
 *     @OA\Schema(type="string")
 *   ),
 *   @OA\Parameter(
 *     name="queryString",
 *     in="query",
 *     required=true,
 *     description="クエリーストリングからのパラメータ例",
 *     @OA\Schema(type="string")
 *   ),
 *   @OA\Response(
 *     response=200,
 *     description="OK",
 *     @OA\JsonContent(
 *       type="object",
 *       @OA\Property(
 *         property="message",
 *         type="string",
 *         description="レスポンスボディjsonパラメータの例"
 *       )
 *     )
 *   ),
 *   @OA\Response(
 *     response=400,
 *     description="Bad Request",
 *     @OA\JsonContent(
 *       type="object",
 *       @OA\Property(
 *         property="message",
 *         type="string",
 *         description="レスポンスボディjsonパラメータの例"
 *       )
 *     )
 *   ),
 *   @OA\Response(
 *     response=401,
 *     description="Unauthorized",
 *     @OA\JsonContent(
 *       type="object",
 *       @OA\Property(
 *         property="message",
 *         type="string",
 *         description="レスポンスボディjsonパラメータの例"
 *       )
 *     )
 *   ),
 *   @OA\Response(
 *     response="default",
 *     description="Unexpected Error",
 *     @OA\JsonContent(
 *       type="object",
 *       @OA\Property(
 *         property="message",
 *         type="string",
 *         description="レスポンスボディjsonパラメータの例"
 *       )
 *     )
 *   )
 * )
 */

JSONファイルの書き出し

下記コマンドでコントローラーの設定ファイルを元にjsonファイルが書き出されます。

php artisan l5-swagger:generate

毎回コマンドの実行が面倒な場合位、.envファイルに下記の設定を追加

L5_SWAGGER_GENERATE_ALWAYS=true

動作の確認

/api/documentation
配下を参照する事で可能

ルーティングに関しても下記のように設定されていればOK