Agent 可行動性說明（OpenAPI）

什麼是 OpenAPI 路徑

OpenAPI 是描述 HTTP API 的標準格式。它把 API 的版本、入口、路徑、參數、請求格式、回應格式、授權方式與共用資料模型整理成外部系統可直接解析的文件。

對這個評分面向來說，重點不只在文件內容，也在於它是否能被穩定找到。

• /.well-known/openapi.json
• /openapi.json
• /swagger.json
• /openapi.yaml / /openapi.yml
• /docs/openapi.json
• /api/openapi.json
• /v3/api-docs

當網站把文件放在這些常見入口時，搜尋系統、文件工具、整合平台與 AI 助理就更容易辨識：這個網站除了有內容頁，也有可被理解與使用的服務能力。

為什麼這會成為評分依據

如果 \`robots.txt\` 在講抓取邊界、\`sitemap.xml\` 在講內容盤點、Meta Tags 在講頁面摘要，那 OpenAPI 講的就是網站的能力邊界。

一份品質良好的 OpenAPI 至少應該回答這些問題：

• 這份 API 是什麼。
• 在哪裡可以呼叫。
• 有哪些操作與路徑。
• 輸入輸出長什麼樣子。
• 哪些能力需要授權。

OpenAPI 能做什麼，不能做什麼

它能做的事

• 讓能力可被發現： 讓外部系統更快知道網站有沒有可呼叫的 API 或可讀取的結構化內容。
• 讓輸入輸出可被理解： 以資料結構定義請求與回應格式，降低整合成本。
• 讓授權邊界可被理解： 透過 securitySchemes 清楚說明 Bearer、OAuth2 或 API Key。
• 讓內容可按需取用： 把 FAQ、活動、價格、條款等資訊變成可結構化查詢的出口。
• 支撐 AI 與工具使用： 讓文件 UI、SDK 產生器、測試工具與 AI 助理更容易接上。

它不能保證的事

• 不能保證排名一定提升： OpenAPI 不是傳統排名因子，但它會影響理解與整合成本。
• 不能取代正式頁面： API 應該是結構化出口，不應取代原本的權威內容頁。
• 不能掩蓋文件與實作不一致： 文件若和真實回應脫節，反而會傷害信任。
• 不能取代安全設計： 有 OpenAPI 不代表權限與公開範圍就合理。

為什麼缺少可發現的 OpenAPI 會直接拉低這項分數

1. 有服務能力，但沒有標準入口

很多網站其實有 API，但能力只藏在前端請求、內部文件或工具介面裡。這代表能力存在，但沒有被清楚整理成外部可理解的入口。

2. 有檔案，但不是合法 OAS 3.x

若文件缺少 openapi、info、paths 或基本結構錯誤，工具鏈與 AI 系統就很難穩定解析。

3. 有路徑，但沒有足夠說明

只有 API 路徑名稱而沒有 summary、資料結構、範例與回應定義，會讓 API 退化成半人工猜測文件。

4. 文件與真實能力脫節

文件若寫的是一套、實際回應是另一套，對使用者與整合方來說，比沒有文件更糟。

5. 對外能力邊界不清楚

不是所有內部 API 都應該公開。高分關鍵不是暴露所有端點，而是把對外可用的能力與內容出口整理清楚。

一般網站也可以怎麼使用 OpenAPI

這一點很關鍵，因為它決定 OpenAPI 會不會被看成「只有平台型網站才需要」的項目。事實上，一般網站也可以把高頻資訊整理成結構化內容 API。

以下內容都很適合 API 化：

• FAQ
• Promotion / campaign 活動資訊
• 價格方案
• 門市與據點資訊
• 客服與聯絡方式
• 配送與退換貨規則
• 服務條款與隱私聲明

一個一般品牌網站就可能整理出這樣的內容型接口：

GET /api/faq
GET /api/promotions
GET /api/promotions/{promotionId}
GET /api/terms/latest
GET /api/privacy/latest
GET /api/store-locations
GET /api/customer-support/channels
GET /api/pricing/plans

如果再把欄位講清楚，價值會更高：

• FAQ API： question、answer、category、locale、updated_at
• Promotion API： title、start_at、end_at、status、canonical_url
• Terms API： version、effective_date、sections[]、locale
• Store API： store_id、address、geo、opening_hours、contact_phone

三種行動情境：從可讀到可行動

這是 OpenAPI 與一般 SEO 工具最容易被忽略的差異：網站不只要能被看見，還要能被 AI Agent 實際使用。

在 AI SEO 時代，OpenAPI 更像「能力說明層」

AI SEO 除了檢查頁面是否易於理解，也關注網站能力是否能被理解與呼叫。對 AI 來說，可按需取用的結構化答案比模糊描述更有價值。

我們如何解讀 OpenAPI 分數

在 Aulait GEO Scorecard 中，OpenAPI 分數不是只看「有沒有 openapi.json」，而是一路往下看文件是否合法、資訊是否完整、路徑是否清楚、資料格式定義是否足夠，以及授權方式是否有被交代。

一、文件結構是否合法

• 是否存在可讀取的 OpenAPI 文件。
• openapi 欄位是否存在且為 OAS 3.x。
• 是否符合基本 OpenAPI 文件結構。

二、基本身份是否清楚

• info.title、info.version、info.description
• servers 是否定義清楚。

三、操作清單是否足夠清楚

• 是否存在 paths。
• 是否有一定數量的 API 路徑。
• operation 是否有 summary / description 與成功回應。

四、輸入輸出是否可被穩定理解

• 請求格式定義
• 回應格式定義
• 參數格式定義
• 範例資料

五、資料模型與授權邊界是否清楚

• components.schemas
• components.securitySchemes
• tags 分類

高分的 OpenAPI 通常長什麼樣子

高分文件通常不是特別長，而是把關鍵資訊整理清楚：

• 有穩定且可預期的公開路徑。
• 規格版本正確且結構合法。
• info、servers、paths 清楚。
• 請求與回應格式具體。
• 有 components.schemas、securitySchemes 與範例資料。

{
  "openapi": "3.1.0",
  "info": {
    "title": "Brand Content API",
    "version": "2026-04",
    "description": "FAQ、活動、條款與門市資訊的結構化內容出口"
  },
  "servers": [{ "url": "https://example.com" }],
  "paths": {
    "/api/faq": {},
    "/api/promotions": {},
    "/api/terms/latest": {}
  }
}

這樣的文件即使沒有複雜交易能力，也已經清楚表達網站願意把重要資訊整理成可被外部系統按需取用的形式。

這項分數代表什麼

OpenAPI 分數反映網站是否已將能力與高價值資訊整理成標準格式，讓外部系統能穩定理解與整合。

對服務型網站來說，它代表能力是否被講清楚；對一般網站來說，它也可以代表 FAQ、活動、條款、隱私、價格與門市資訊是否已被整理成結構化內容出口。

官方規範與參考連結

下列 OpenAPI Initiative 正式規範與官方學習文件，是本評分面向的外部依據。