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 を修正する必要があります。
コードのサンプルはここにあります。(関係ないコードも入っていますが・・・)