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

# 経緯
- Laravelの新規プロジェクトを作成するにあたってAPIドキュメントが必要になった
- [L5-Swagger](https://github.com/DarkaOnLine/L5-Swagger) を使ってみたが、記載量が多すぎて心が折れかけた
- FEからPostmanに対応してくれという声があがったので、もっと楽できないものかと探していたら [Scribe](https://github.com/knuckleswtf/scribe) に出会って幸せになった

# とあるController.php の Before After

## before
```php
    /**
     * @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とは
以下コマンドを実行すると[こんな感じ](https://demo.scribe.knuckles.wtf/#introduction)のAPIドキュメントを吐き出してくれる
```bash
 php artisan scribe:generate
```

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

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

# Scribeの特徴


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

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

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

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

こんな感じで表示される
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/167604/f3ac245c-3cf3-d132-62d1-4ae13b20407c.png)

Web上でテスト実行が可能。Authorization headerに Bearer を設定し認証状態でAPIをコールすることも可能
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/167604/6a4ac70c-a2d7-f140-e339-4e6874552bde.png)

APIドキュメント生成時にAPIのエンドポイントを呼び出して、サンプルの応答を自動出力してくれる
デフォルトはGETのみ対応しているが設定を変えるとPOSTやPATCHに対応
```php
                '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ドキュメント出力時に認証状態でリクエストしてくれる

```php
        /*
         * 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をダウンロードできる
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/167604/c2b702eb-b189-9741-ef24-f7928673691c.png)

インポートするとこんな感じ
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/167604/01d377e1-c531-bdb3-a14e-d155f8b0171e.png)


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