ianhuang筆記THE ADVENTURER'S JOURNAL
知識世界・持續探索中

ADVENTURE JOURNAL · 探索筆記

API 文件工具:OpenAPI、Slate 與 apiDoc 的選擇

任務導覽 TABLE OF CONTENTS

補上契約來源、生成方式與限制,提供最小 OpenAPI 文件。

適用:HTTP API文件規劃;工具產物不會自動代替後端驗證或契約測試。

比較

工具輸入來源適合與限制
OpenAPI/Swagger UI結構化API規格可互動、生成工具;規格仍要與實作一致
SlateMarkdown與範例易寫敘述;不是自動驗證HTTP schema
apiDoc程式碼註解靠近實作;需維護註解與生成版本

OpenAPI是規格,SwaggerUI是呈現與操作工具,兩者不能只當同一產品名稱。Spring的生成整合見 Swagger筆記 。

最小契約

openapi: 3.0.3
info:
  title: 筆記 API
  version: 1.0.0
paths:
  /tasks:
    get:
      summary: 列出任務
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [id, title]
                  properties:
                    id: {type: string}
                    title: {type: string}

在相容的OpenAPIvalidator檢查後用檔案工具呈現,應有GET /tasks與回應欄位。此例故意只涵蓋成功清單,沒有分頁/授權;真正API補上錯誤、認證、限制與範例。

維護

選擇spec-first或code-first後定義唯一權威來源,CI檢查生成差異與實際響應schema。工具版本鎖定,別在每次build抓latest生成不同檔案。檔案示例用本地假資料,不含真實token/個資;公開範圍與程式原始碼範圍分開考慮。

參考資料

冒險者留言

comments powered by Disqus

搜尋筆記

輸入關鍵字,探索所有筆記。

ESC 關閉 · 搜尋標題、標籤與文章全文