LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

離線文件包

除了這個文件網站,平台同時提供一份版本化的離線文件包,給需要離線作業、把契約釘在某一版、或把文件餵給 AI 工具的場合。網站與文件包由同一次 build 從同一份來源產生,不會漂移。

內容

路徑 內容
openapi/third-party-api.v1.yaml 版本化 OpenAPI 契約(原始檔,未經改寫)
schemas/*.json 從 OpenAPI 抽出的 JSON Schema,逐個 schema 一個檔
guides/*.md 本網站的全部指南(Markdown 原文)
examples/ 可執行的 Node 與 Python 範例、mock server、.env.example
llms.txt 給 AI 開發工具讀的索引(英文)
llms-full.txt 全文串接,單檔可餵給 AI 工具(英文索引+中文內文)
CHANGELOG.md 變更紀錄
manifest.json 版本、來源 commit、每個檔案的 sha256

驗證完整性

unzip lightup-third-party-api-v1.<version>.zip -d bundle
cd bundle
# manifest.json 的 files[] 每一項都有 sha256

manifest.json 長這樣:

{
  "bundle": "lightup-third-party-api-v1",
  "contractVersion": "…",
  "sourceCommit": "…",
  "generatedAt": "…",
  "placeholders": [],
  "publishable": true,
  "apiHost": "api.lightup.tech",
  "docsHost": "developers.lightup.tech",
  "preview": false,
  "files": [{ "path": "openapi/…", "bytes": 0, "sha256": "…" }]
}

sourceCommit 是產生這份包的 repo commit。回報問題時附上 contractVersion 與 sourceCommit,平台就知道你看的是哪一版契約。

佔位符

文件包與網站不預填不存在的網址:位址由契約決定,定案後 build 自動填入,未定案的就留成佔位符給你看見。

位址 狀態
第三方 API host 已定案:api.lightup.tech
開發者文件網站 host 已定案:developers.lightup.tech

manifest.json 有幾個欄位可以直接判讀:placeholders 列出仍未填的佔位符(現在是空的)、hostGates 列出契約自己標記為待定的位址(也是空的),兩個都空 publishable 才是 true;apiHost/docsHost 是實際填入的值;preview 表示這份包產生時端點是否仍未開放(現在是 false)。

端點已上線,但第三方整合是逐租戶生效的。 api.lightup.tech 接受請求,Gateway 已部署;租戶的方案不含第三方整合或尚未開啟時,每個呼叫都是 403 tenant_not_enabled。能力目錄五項自 2026-10-05 起全部是 ga(正式),適用相容與棄用政策。

這份包不含什麼

只發布經核准的對外契約。內部 proto、BFF 路由、管理 API、平台施工計畫與客戶個案都不在裡面,也不會在裡面。