Laravel に Swagger UI を入れる

REST API を作る際、 Open API (Swagger) でドキュメントを書くことがあると思います。Laravel で API 作るなら一緒に Swagger UI も乗せてしまえば動作確認が楽かな、ということで設定してみました。

まずは Swagger UI をインストールします。

npm i -D swagger-ui

JavaScript と CSS 読み込み

次は js と css を読み込むスクリプトを書きます。Laravel のプロジェクトを初期化した際、 Laravel Mix という webpack のようなものが一緒に入るのでそれを利用します。

resources/js/app.js に以下の2行を追加します。

require('swagger-ui/dist/swagger-ui.css')
window.SwaggerUI = require('swagger-ui')

app.js を保存したら、以下のコマンドを実行します。

npm run prod

そうすると public/js/app.js が生成されます。

blade とルーティングを書く

resources/views/swagger-ui.blade.php を作成します。url の /api/v1/open-api の部分は Open API の json か yaml のパスに書き換えてください。

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>Swagger UI</title>

        <script src="/js/app.js"></script>
    </head>
    <body class="antialiased">
        <main id="swagger-ui">
        </main>
        <script>
            const ui = SwaggerUI({
                url: "/api/v1/open-api",
                dom_id: '#swagger-ui',
            })
        </script>
    </body>
</html>

最後にルーティングを追加します。routes/web.php に以下を追加します。

Route::get('swagger-ui', function () {
    return view('swagger-ui');
});

Swagger UI から API を試そうとした時に CORS 関連のエラーがブラウザのコンソールに出る場合があります。その場合は適切な Access-Control-Allow-Origin ヘッダを返却するよう API を修正する必要があります。

コードのサンプルはここにあります。（関係ないコードも入っていますが・・・）

JavaScript と CSS 読み込み

blade とルーティングを書く

関連記事:

コメントを残す コメントをキャンセル

コメントを残すコメントをキャンセル