如何在 Mintlify 中匯入 OpenAPI 規格以生成互動式 API 參考文件

Mintlify 能將 OpenAPI 3.0 與 3.1 規格（支援 JSON 與 YAML 格式）直接轉換為結構清晰、具備互動能力的現代化 API 參考文件。開發與技術寫作團隊不再需要手動維護繁瑣的請求參數表格、標頭說明或回應欄位模型，Mintlify 會自動解析規格檔案，產生多語言程式碼範例生成器，並提供讓開發者直接在瀏覽器中發送即時請求測試的 API 控制台（Playground）。

在系統架構上，Mintlify 採用「文件即程式碼」（Docs-as-code）的工作流程。OpenAPI 規格檔案與 Markdown 文件一同保存在 Git 儲存庫中，由核心設定檔（docs.json，早期版本為 mint.json）統整全域結構。團隊可依據業務需要選擇兩種接入途徑：一是完全免人工維護的全自動文件生成，由規格檔案驅動整套參考手冊；二是將 OpenAPI 端點精準綁定至特定 MDX 頁面中，在保留自動化參數與測試控制台的同時，擴充業務教學、架構指引與深度說明。

先決條件與規格要求

在設定 Mintlify 之前，請確認介面規格檔案符合平台標準：

• 規格版本： Mintlify 原生支援 OpenAPI Specification (OAS) 3.0 與 3.1 版本。若現有規格仍停留在 Swagger 2.0，請先將其升級轉換為 OpenAPI 3.0。
• 檔案格式： 支援標準 JSON（.json）與 YAML（.yaml 或 .yml）。
• 參照限制（$ref）： Mintlify 支援單一檔案內的內部參照（如 $ref: '#/components/schemas/User'），但不支援跨檔案的外部綱要參照。若團隊的規格分散在多個獨立檔案中，在匯入 Mintlify 前必須先使用工具（例如 Redocly CLI 或 @apidevtools/swagger-cli）將其打包整合為單一檔案。

第一步：放置 OpenAPI 規格檔案

團隊可透過本地儲存庫歸檔或遠端 URL 兩種方式接入規格檔案：

1. 本地儲存庫託管（推薦）： 將規格檔案直接提交至文件儲存庫中。常見做法是存放在專案根目錄（例如 openapi.json、openapi.yaml）或專屬的介面目錄中（例如 api-reference/openapi.json 或 specs/v1.yaml）。

2. 託管遠端 URL： 若後端 CI/CD 流程會自動建置並發布最新的 OpenAPI 檔案至物件儲存服務或 CDN，可直接在設定中指定 HTTPS 連結（例如 https://api.example.com/specs/openapi.json）。在線上正式環境中，遠端規格必須採用 HTTPS 協定。

第二步：在 docs.json 中設定導覽

要在文件左側側邊欄中呈現 API 參考頁面，需在 docs.json 的 navigation 節點下進行關聯。

方案 A：全自動產生參考文件

若希望 Mintlify 自動擷取規格中的所有路徑，並依據 OpenAPI 的 tags 標籤完成分組與頁面渲染，只需在導覽分頁或分組中直接宣告規格路徑：

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Acme API Docs",
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          {
            "group": "入門指南",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "openapi": "openapi.json"
      }
    ]
  }
}

在此設定下，Mintlify 會自動掃描 paths 下定義的所有介面，提取 HTTP 請求方法、介面摘要、詳細說明、參數列表與回應架構，完全不需撰寫任何 MDX 檔案即可生成整套 API 瀏覽目錄。

多規格協同管理

若系統包含多個獨立微服務或拆分了不同的 API 版本，可以在 openapi 屬性中傳入檔案路徑陣列：

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": [
          "specs/v1/auth.json",
          "specs/v1/billing.json",
          "specs/v2/core.json"
        ]
      }
    ]
  }
}

第三步：借助 MDX 頁面實現精細化文件客製

雖然全自動模式省時省力，但技術寫作者通常需要在特定介面旁補充業務脈絡、前置條件、頻控警告或架構循序圖。Mintlify 支援透過 MDX 的 Frontmatter 屬性將頁面與具體介面緊密綁定。

1. 將 MDX 頁面綁定至指定介面

新增一個 MDX 檔案（例如 api-reference/users/create.mdx），在開頭的 Frontmatter 中透過 openapi 欄位宣告對應的 HTTP 方法與路由：

---
title: "建立使用者"
sidebarTitle: "建立使用者"
description: "在目前組織下註冊新的使用者帳戶"
openapi: "POST /v1/users"
---

## 業務說明

在呼叫此介面前，請確認用戶端已完成身分驗證，並具備 `users:write` 授權範圍。

<Warning>
  使用者的電子郵件地址在組織內必須唯一。若傳入已存在的郵件地址，系統將回傳 `409 Conflict` 錯誤。
</Warning>

## Webhook 回呼通知

使用者建立成功後，系統將自動觸發 `user.created` 事件，並向您設定的 Webhook 端點發送資料通知。

Mintlify 解析到 POST /v1/users 後，會自動將規格中對應的請求構建器、請求參數說明和回應結構注入至當前頁面中，並與自訂的 MDX 正文自然融合。

若專案中引入了多個規格檔案，為避免路由衝突，需在前面註明規格檔案路徑：

---
title: "建立使用者"
openapi: "specs/v1/auth.json POST /v1/users"
---

2. 使用 Mintlify 官方工具批次產生 MDX 範本

當現有介面數量龐大且希望逐一進行細部調整時，可使用官方提供的抓取生成腳本：

npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference

該指令會自動解析規格並在 api-reference 目錄下產生各介面對應的獨立 MDX 檔案，且均已設定好相應的 Frontmatter 屬性，方便團隊快速編輯。

第四步：設定互動式 API 控制台（Playground）

Mintlify 的即時控制台允許開發者在文件頁面內直接填寫參數並發送真實 HTTP 請求。為了確保測試體驗流暢，需在規格檔案與全域設定中做好以下配置：

1. 指定 API 基礎伺服器位址（Base URL）

Mintlify 會直接讀取 OpenAPI 規格中的 servers 陣列作為請求目標位址：

servers:
  - url: https://api.example.com/v1
    description: 正式環境
  - url: https://staging.api.example.com/v1
    description: 測試沙箱

當定義了多個伺服器位址時，控制台介面會自動呈現環境下拉式切換選單。

2. 設定驗證憑證與預設測試值

在規格的 components.securitySchemes 中宣告認證方案，控制台便會自動呈現對應的輸入欄位（支援 Bearer Token、API Key、Basic Auth 等）：

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 請輸入您的 API 存取權杖
security:
  - bearerAuth: []

為了方便讀者快速測試沙箱介面，可在安全方案中加入 x-default 擴充欄位以提供預置測試金鑰：

{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "x-default": "demo_pk_live_testing123"
      }
    }
  }
}

3. 解決跨來源資源共用（CORS）限制

由於互動式控制台發起的請求來自讀者的瀏覽器客戶端，後端介面伺服器必須正確回應跨網域預檢與標頭，否則瀏覽器將阻擋網路通訊：

• Access-Control-Allow-Origin: *（或您的文件專屬網域）
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
• Access-Control-Allow-Headers: Authorization, Content-Type, X-API-Key

若伺服器未放行 OPTIONS 預檢請求，會導致控制台測試失敗，即便本機 curl 能夠正常連線。

第五步：利用 OpenAPI Overlays 無侵入式調整規格

技術寫作者經常面臨一項實務挑戰：後端程式碼自動產生的規格往往包含內部未公開介面，或是欄位描述晦澀，而直接修改原始碼或維護分支規格又極易造成維護失步。Mintlify 支援 OpenAPI Overlay 規格（v1.1.0），允許在文件建置時透過修補檔案無損微調規格。

建立疊加層檔案（例如 overlays/public-filter.yaml），使用標準 JSONPath 語法執行 update、remove 或 copy 操作：

overlay: 1.1.0
info:
  title: 公開文件微調配置
  version: 1.0.0
extends: ./openapi.json
actions:
  - target: $.info.description
    update: "歡迎查閱 Acme 官方開發者文件，您可在此探索介面細節並進行線上測試。"
  - target: $.paths['/internal/system-health']
    remove: true
  - target: $.paths['/v1/billing'].post.summary
    update: "建立週期性扣款訂閱"

隨後在 docs.json 中關聯該疊加層：

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": {
          "source": "openapi.json",
          "overlays": ["overlays/public-filter.yaml"]
        }
      }
    ]
  }
}

Mintlify 在編譯網站時會自動套用補丁，既隱藏了內部路徑、改善了對外說明文字，又維護了上游工程原始碼規格的完整性。

第六步：本機除錯與 CI/CD 自動化驗證

在推送至正式發布前，使用 Mintlify CLI 在本機進行即時預覽與規格驗證：

1. 安裝並啟動開發預覽伺服器：

   npm i -g mintlify
   mint dev
   

2. 除錯本機正在運行的規格服務： 若規格由本機後端介面動態提供（例如 http://localhost:8000/openapi.json），啟動時需附加授權參數：

   mint dev --local-schema
   

3. 執行嚴格格式驗證： 排查失效的模式參照、遺漏的回應結構與語法錯誤：

   mint validate
   

4. 整合持續整合（CI）流程： 將 mint validate 納入 GitHub Actions 或 GitLab CI 流程中。每當研發人員提交新的介面定義時，CI 會自動驗證參照完整性，有效避免有瑕疵的規格影響線上文件。

參考資料

• OpenAPI setup - Mintlify
• API playground overview - Mintlify
• Navigation - Mintlify
• Troubleshooting - Mintlify