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