Laravel+Scribeで簡単にAPIドキュメントを作ってみる - クイックエンジニアリングブログ

こんにちは！ソフトウェアエンジニアのたろーです。

在宅勤務が増えて対面コミュニケーションが減った分、仕様書などのドキュメント類の重要さ改めて実感する機会が増えました。

そのような中で、
「とりあえずLaravelで作ったAPIの仕様書を簡単につくりたいなー」
「Swaggerは使ったことあるけど他にもっと簡単に使えるものないかな〜」
と思い調べていたところ、Scribeというツールにたどり着き軽い気持ちで使ってみたらとても簡単に導入できたので紹介しようと思います！

Scribeとは
サンプルAPI作成
設定
- Scribeインストール
- Scribe設定変更
PHPdoc修正
動かしてみる
- ドキュメント生成
- APIドキュメント確認
感想
- 良いと思った点
- 気になる点
最後に

Scribeとは

Laravel対応のAPIドキュメントジェネレーター
PHPdocからAPI仕様書のwebページが作れる。
仕様書上で実際にリクエスト投げてみるようなテストもできる。
PostmanやOpenAPI/Swaggerの設定ファイルの出力もできる。

などなど簡単にできる便利ツールです。
公式ドキュメント

サンプルAPI作成

とりあえずサンプル用に簡単なGETとPOSTのAPIを作ってみます。

$ php artisan make:controller Api/V1/HelloController

HelloController.php

<?php

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class HelloController extends Controller
{

    /**
     * (GET)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     */
    public function get(Request $request)
    {
        $name = $request->input('name','名無し');

        return response()->json([
            'message' => sprintf('Hello %sさん!!GETだよ！!', $name),
            'status'  => 200,
        ]);

    }

    /**
     * (POST)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     */
    public function post(Request $request)
    {
        $name = $request->input('name','名無し');

        return response()->json([
            'message' => sprintf('Hello %sさん!!POSTやで!!', $name),
            'status'  => 200,
        ]);

    }
}

routes/api.php

<?php

Route::get('/v1/hello', 'Api\V1\HelloController@get');
Route::post('/v1/hello', 'Api\V1\HelloController@post');

設定

Scribeインストール

composerでインストール

$ composer require --dev knuckleswtf/scribe
$ composer show -i

knuckleswtf/scribe   2.7.10    Generate API documentation for humans from your Laravel codebase

設定ファイル生成

$ php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config

基本的なインストール手順はこれだけです！

Scribe設定変更

設定ファイルがconfig/scribe.phpに吐き出されているので設定を変更します。

ルートのマッチパターン変更
今回はapiのみを対象にしたいのでroutes.match.prefixesをapiに変更します。

 /*
  * Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
  */
 // 'prefixes' => ['*'],
 'prefixes' => ['api/*'],

環境に合わせて対象URLを変更
今回はビルトインサーバの8000ポートで動かします。

   /*
    * The base URL to be used in examples. If this is empty, Scribe will use the value of config('app.url').
    */
 // 'base_url' => null,
 'base_url' => 'http://localhost:8000',

設定をしなければconfig/app.phpのurlを自動で設定してくれます。環境のURLに合わせて変更してください。

PHPdoc修正

ドキュメント出力用にPHPdocを該当コントローラに記載していきます。

GETメソッド用
@queryParam はURLパラメータクエリを記載します。

パラメータ名　型　required|optional 説明

の順で記載です。

@response にはサンプルレスポンスを記載します。
レスポンスの直前にステータスコードを記載することでステータスコードごとにレスポンスを記載できます。
記載量が多くなってしまう場合は@responseFileというアノテーションで外部ファイルを読み込ませることもできるようです。

    /**
     * (GET)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     * @group hello
     * @queryParam name string  呼んで欲しい名前
     * @response 200{
     *   "message":"Hello 名無しさん!!GETだよ!!",
     *   "status" :200
     * }
     */
    public function get(Request $request)

POSTメソッド用
基本的にはGETと同じですが、今回はリクエストボディーを受け付けるので @queryParamでなく @bodyParam といアノテーションを記載します。

   /**
     * (POST)名前を呼んで挨拶を返してくれるAPI
     *
     * @param Request $request
     * @return JsonResponse
     *
     * @group hello
     * @bodyParam name string  呼んで欲しい名前
     * @response 200{
     *   "message":"Hello 名無しさん!!POSTやで!!",
     *   "status" :200
     * }
     */

他にもアノテーションが用意されており、ドキュント生成時のハンドリングが行えるので是非公式ドキュメントを読んでみてください。

動かしてみる

ドキュメント生成

ドキュメント生成
artisanコマンドが用意されており、実行することで生成、対象ディレクトリへ配布されます。

$ php artisan scribe:generate

ビルトインサーバ立ち上げ
今回はビルトインサーバで立ち上げます。実際にwebサーバやwebコンテナ上でアプリが立ち上がっている場合は不要です。

$ php artisan serve

APIドキュメント確認

http://localhost:8000/docs/index.htmlへブラウザでアクセスします。

f:id:aimstogeek:20210714113824p:plain

できました!! 今回作った2つのAPIが表示されています。
APIのパスやパラメータ、サンプルレスポンスがroute.phpやPHPdocの内容に沿って表示されているのがわかります。

「Try it out」ボタンをクリックすると、リクエストパラメータに入力ボックスが表示されるので、ここから実際にAPIリクエストをなげてレスポンスを確認することもできます。 f:id:aimstogeek:20210714114803p:plain

感想

良いと思った点

とにかく導入と記述がとても簡単！
APIの設計と一部コーディングを並列で行える。
簡単なテストであれば作成されたドキュメント上で行える。

気になる点

複雑なAPIやフィールドやパラメータが多いAPIだとPHPdocがとても長くなる。
個人的な感想ですが、主にレスポンスフィールド周りのドキュメントUIが少し見づらい。
APIモックを同時に作成したり、ドキュメントはドキュメントとして構成管理していく場合にはSwaggerの方が良さそう。

最後に

軽い気持ちで試してみたScribeですが想像以上に簡単に導入できてしまいました！
もっとリッチなことをやりたい場合はSwagger等を利用することも考慮に入れた方が良さそうですが、ScribeからSwaggerの設定ファイルを吐き出せるので、「とりあえずScribeでやってみて考えようか」くらいの気持ちで導入してみるのも良いかもしれません！

在宅勤務が増えコミュニケーションの方法が変化する中で、設計書やドキュメントの存在は非常に重要になってくると思いますので、充実化・整備しつつ自動化できるところは自動化して開発パフォーマンスを上げていきましょう！

＼\『真のユーザーファーストでマーケットを創造する』仲間を募集中です!! /／

919.jp