前言

其實基本上API文件很多前輩都是在開發的時候，做API紀錄用的比如（scribe、swagger)，但我想在這裡分享的比較像是一個事前的規劃文件。

這個目的主要在於：

• 在開發前先想法有哪幾個API要開，甚至在validation的時候要驗證哪些輸入、以及要返回什麼response。
• 有了這個規劃文件後去跟業主確認我這些API是做什麼樣的功能，符不符合需求，等到都確認之後，就可以根據這些API去做開發，不會還需要再開發的過程中還要去想現在是否所有的API都開發完成了。

API文件規劃

以下是我大概的一個顯示方式。

• 參數的部分

  這裡我就是針對輸入進來的參數做了一些預想，並打算引用laravel的一些預設的驗證規則，舉個例子，這裡我們在更新的部分的需求主要就是：

  • 所有的欄位都可以做更新，但更新的屬性必須在對應的表中存在。
  • 然後這裡我是打算用id儲存所以屬性的部分大多用數字。
  • 等級的部分就是上限100等。
  • 技能的部分讓使用者最少輸入一個，最多輸入四個。

• response

  就是大概想像一下我回應給前端的大概是一個怎樣的內容，在前期和前端溝通的時候可能也是比較重要的，比如你回應的檔裡面key是什麼，他要如何接。

小總結

關於這些文件的規劃，可能我的方法比較不正式（畢竟是第一次做這樣的專案)，隨著之後開發的經驗越來越堆一定會和現在這個版本有所不同，但這裡我就是試著讓自己養成習慣以及去練習。