2023-11-09|閱讀時間 ‧ 約 5 分鐘

Laravel swagger

我對於自己開發的API會習慣性寫一份swagger文件方便前端串接，但因為這些文件都是存在我個人的swagger帳號，且會受限於免費版限制，再加上剛好跟PM在討論如何維護我們的文件，於是我就開始著手將swagger自己部署到公司管理後台。

這樣做的好處：

(1)後端都可以編輯

(2)文件隸屬於公司底下且不用另外付費

(3)git版控，可以清楚知道誰動了什麼

實作

安裝

npm install swagger-ui

設定

step1: 存放yaml檔

因為這份swagger是要開放給外界看到的，所以會需要將檔案放在public資料夾，因為公司有多個產品，所以我開的路徑為：public/documents/aaa-api.yaml, public/documents/bbb-api.yaml

step2: js檔設定檔

在resource/js資料夾中新增每一份yaml檔要用的js設定：

aaa-swager.yaml

import SwaggerUI from "swagger-ui";

import "swagger-ui/dist/swagger-ui.css";

SwaggerUI({

    dom_id: "#swagger-api", // 代表他會去找html中元素id是swagger-api的，然後將文件載入

    url: "https://xxxxxx/documents/aaa-api.yaml", // yaml檔位置，js會去抓

});

bbb-swagger.yaml

import SwaggerUI from "swagger-ui";

import "swagger-ui/dist/swagger-ui.css";

SwaggerUI({

    dom_id: "#swagger-api", // 代表他會去找html中元素id是swagger-api的，然後將文件載入

    url: "https://xxxxxx/documents/bbb-api.yaml", // yaml檔位置，js會去抓

});

step3: webpack

設定

到webpack.mix.js檔，新增以下

mix.js("resources/js/aaa-swagger.js", "public/js")

    .js("resources/js/bbb-swagger.js", "public/js")

運行

npm run dev

將在resource/js資料夾的js打包到public/js資料夾裡，這樣我們的html檔就能載入他們，背後js會幫我們根據設定檔把畫面載入到某一個div上。

step4: 寫blade樣板

新增swagger.blade.php

<!DOCTYPE html>

<html lang="en">

<head>

    <meta charset="UTF-8">

    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title>api</title>

</head>

<body>

    <div id="swagger-api"></div>

    <script src="{{ mix('js/' . $fileName) }}"></script>

</body>

</html>

因為每一份api文件樣式都一樣，所以我才只開一份blade，需要載入的檔案位置再透過api route傳就好。

step5: route

到web.php新增以下路由：

Route::group([

    'prefix' => 'documents',

    'middleware' => ['auth:sanctum'] // 登入驗證,避免api公開

], function(){

    Route::get('/aaa',  function () {

        return view('swagger')->with('fileName', 'aaa-swagger.js');

    });    Route::get('/bbb',  function () {

        return view('swagger')->with('fileName', 'bbb-swagger.js');

    });});

step6:開cors

step7: 運行

composer artisan optimize

之後到你設定好的路由，就可以看到成果了

分享至

成為作者繼續創作的動力吧！

好好生活好好愛

追蹤

從 Google News 追蹤更多 vocus 的最新精選內容

你可能也想看

發表回應

成為會員後即可發表留言