我：「我不想寫文件！」
也是我：「為什麼沒有文件！」
身為一個 Web 後端工程師，既然不可能不寫文件，如何讓文件更好寫？本系列文將針對 Web API 的文件撰寫的一些方法與心得進行介紹。

完整的 API 資訊配上良好的排版，才能讓文件發揮它應有的功能：資訊傳遞。

我在職涯的開始曾經擔任手機 App 開發者，多數的功能都會需要串接 Web API 才能提供使用者完整的功能，收到的規格文件多半是 Word (或 PDF) 中列出許許多多的表格或是直接提供一個連結並以網頁呈現。後來改當 Web 後端工程師後，除了串接服務時需要閱讀這些文件，我也開始撰寫規格文件，成了文件的提供者。

格式五花八門，身為開發者該怎麼寫？身為使用者又該怎麼看？本系列文章以 HTTP Web API 為主，因此我們要釐清傳遞的資訊內容，必須先理解什麼是 Web API 及 HTTP，知道要提供那些資訊。

Web API 完整名稱是 Web Application Programming Interface，由名稱可知道它是透過網路 (Web) 提供應用服務 (Application) 的介面 (Interface)，也就是說提供的資訊要包含網路通訊協定類型、應用服務的功能說明及其介面定義。

HTTP 是現在 Web API 的主流通訊協定之一，由客戶端主動向伺服器端發出請求後，伺服器端會針對該請求做出回應。因此在 HTTP API 的規格文件中應包含以下請求的內容：

• Method：GET、POST、PUT、PATCH、DELETE 等等
• URI：要操作的資源位置，通常是 URL 形式
• Header：以 Key-Value 形式傳遞 metadata
• Body：內容資料，不是每個請求都有 body

而回應的內容則包含：

• Status：200 Ok、400 Bad Request、500 Internal Server Error 等等
• Header：以 Key-Value 形式傳遞 metadata
• Body：內容資料，不是每個回應都有 body

從上述內容可以發現，除了應用內容會依各服務不同，其他要提供的內容似乎滿固定的，那有沒有麼什麼共用的規格可以照著寫就好？有！明天起將介紹 OpenAPI (或部分人認識的名字是 Swagger) 技術規範由來及其細節。