Scribeを使ったLaravel APIの自動ドキュメンテーション

9268 ワード
scribe swagger Laravel Postman Laravel テキストリンク

経緯

  • Laravelの新規プロジェクトを作成するにあたってAPIドキュメントが必要になった
  • L5-Swagger を使ってみたが、記載量が多すぎて心が折れかけた
  • FEからPostmanに対応してくれという声があがったので、もっと楽できないものかと探していたら Scribe に出会って幸せになった

とあるController.php の Before After

before

    /**
     * @OA\Get(
     *     path="/admin/setting/organization_users",
     *     tags={"/admin/setting"},
     *     summary="組織ユーザー検索",
     *     security={{"apiAuth": {}}},
     *     @OA\Parameter(
     *         description="キーワード(組織ユーザーID,組織ユーザーコード,組織ユーザー名,組織ユーザー電話番号)",
     *         name="keyword",
     *         @OA\Schema(type="string"),
     *         in="query",
     *     ),
     *     @OA\Parameter(
     *         description="組織ユーザー名",
     *         name="name",
     *         @OA\Schema(type="string"),
     *         in="query",
     *     ),
     *     @OA\Parameter(
     *         description="組織ユーザーコード",
     *         name="code",
     *         @OA\Schema(type="string"),
     *         in="query",
     *     ),
     *     @OA\Parameter(
     *         description="組織ユーザータイプID",
     *         name="organization_type_id",
     *         @OA\Schema(type="string"),
     *         in="query",
     *     ),
     *     @OA\Parameter(
     *         description="組織ユーザーステータスID",
     *         name="organization_status_id",
     *         @OA\Schema(type="string"),
     *         in="query",
     *     ),
     *     @OA\Parameter(
     *         description="作成日 (From)",
     *         name="from_created_on",
     *         @OA\Schema(type="string"),
     *         in="query",
     *     ),
     *     @OA\Parameter(
     *         description="作成日 (To)",
     *         name="to_created_on",
     *         @OA\Schema(type="string"),
     *         in="query",
     *     ),
     *     @OA\Parameter(name="per_page", description="データ取得件数", in="query", required=true, @OA\Schema(type="integer"), example=10),
     *     @OA\Parameter(name="page", description="ページ番号", in="query", required=true, @OA\Schema(type="integer"), example=1),
     *     @OA\Parameter(name="order_column", description="ソートカラム (取得項目の全物理キーを設定できる)", in="query", @OA\Schema(type="integer")),
     *     @OA\Parameter(name="order_direction", description="ソート順 (desc or asc)", in="query", @OA\Schema(type="string")),
     *     @OA\Response(response=200, description="成功", @OA\MediaType(mediaType="application/json"))
     * )
     * @param IndexRequest $request
     * @param IndexAction $action
     * @return IndexResource
     */
    public function index(IndexRequest $request, IndexAction $action): JsonResource

After

    /**
     * 組織検索
     *
     * 組織一覧を取得する
     * @authenticated
     * @group Admin/Setting
     */
    public function index(IndexRequest $request, IndexAction $action): JsonResource

Scribeとは

以下コマンドを実行するとこんな感じのAPIドキュメントを吐き出してくれる

 php artisan scribe:generate

公式ドキュメントはこちら
https://scribe.knuckles.wtf/laravel/
https://github.com/knuckleswtf/scribe

日本語のインストール手順はこちらの記事に詳しく記載されているので参考まで
https://zenn.dev/kotti/articles/954de428831a98

Scribeの特徴

FormRequestsやvalidation rulesを自動で解析してrequestを作ってくれる（神）
Requestsのrules設定だけでもドキュメントを吐き出してくれるが・・・

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules(): array
    {
        return [
            'name' => ['nullable', 'string', 'max:255'],
        ];
    }

同ファイル内に以下のような記載をしておくと備考のコメントや参考値を設定してくれる

    /**
     * パラメータ設定
     *
     * @return array
     */
    public function queryParameters(): array
    {
        return [
            'name' => ['description' => '組織名',  'example' => '組織']
        ];
    }

こんな感じで表示される

Web上でテスト実行が可能。Authorization headerに Bearer を設定し認証状態でAPIをコールすることも可能

APIドキュメント生成時にAPIのエンドポイントを呼び出して、サンプルの応答を自動出力してくれる
デフォルトはGETのみ対応しているが設定を変えるとPOSTやPATCHに対応

                'response_calls' => [
                    /*
                     * API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc).
                     * List the methods here or use '*' to mean all methods. Leave empty to disable API calls.
                     */
                    'methods' => [
                        'GET'
                        'POST',
                        'PATCH'
                    ],

以下のように設定をしておくとAPIドキュメント出力時に認証状態でリクエストしてくれる

        /*
         * The value of the parameter to be used by Scribe to authenticate response calls.
         * This will NOT be included in the generated documentation.
         * If this value is empty, Scribe will use a random value.
         */
        'use_value' => env('SCRIBE_AUTH_KEY'),

デフォルトでpostmanのcollectionに対応している
赤枠をクリックするとcollection.jsonをダウンロードできる

インポートするとこんな感じ

あとがき

いろいろ便利なScribeですが、毎回手動でAPIドキュメントを出力したり認証キーを作り直すのも面倒なので、
Github ActionsでAPIドキュメントの出力を自動化するとさらに幸せになれそう
開発が一息ついたら自動化してみます