# Ch 13. 撰寫 API 設計文件

:::success
文件是 API 的第 3 個 UI，也是最重要的那個
:::

## API 文件的重要性
* 文件是供需方之間最主要的溝通管道
供應方藉由文件表達 API 的設計理念，使用方透過文件來瞭解如何將其融合進自己的應用。
* 文件需要簡單易讀
沒有人想浪費時間去觀看 API 的 Source Code，因為費時又費力，寧願自己建一個或是用其他文件寫的簡單易讀的。
* 文件需要好的組職與編排
好的文件可以讓使用者由簡入深的瞭解 API，讓使用者明確的知道該做什麼以及如何找到他所需要的功能。

## API 描述文件的格式
* 傳統文件通常都是用 PDF、Word、HTML 等，在使用性上有著許多限制。
* 新的 API 文件會記載 API 所有詳細的技術資料，並且可以交由機器讀取設定並產生出可供人閱讀的文件、用戶端 / 服務端的 Sample Code。
* 部分 API 描述格式可以在其中設定 Authorization、Route、Config 等特性，APIM (API Management) 讀入後就能自動將設定套入到佈署好的服務中。

:::info
不過其實日常開發都是透過在程式內加上一些標籤或註解，並安裝對應的套件，讓服務自動產生出對應的 API 文件。
:::

### OpenAPI
* 最普遍用於記載 API 的詳細定義，Net Core 預設安裝。
* 舊名 Swagger，於 2015 年 Swagger 捐贈給 OpenAPI 計畫。
* 可用 Json 或 Yaml 來產生功能完整的 SwaggerUI，不但可以看文件規格，也可以直接進行 API 調用的測試。

### API Blueprint
* 由 Apiary 公司開發，後來被甲骨文收購。
* 以 Markdown 為基礎進行撰寫，因此就算不交由機器幫忙產生文件，人類也可方便閱讀。
* 原公司有實作自己的編輯器，但只要能預覽 Markdown 結果的編輯器都能方便地進行編輯。


### RAML (RESTful API Modeling Language，RESTful API 建模語言)
* 最初是 MuleSoft 開發，後來開源。
* 以 Yaml 為基礎進行撰寫。
* 原公司有實作自己的編輯器，可以產生人讀及機讀文件。
* 內容是基於 REST API 的規則來設計，包含資源、方法、參數、回應等等，因此其他以 HTTP 為基礎的的 API 規格也能使用。

## **Additional**

### JSON Schema
* JSON Schema 用於定義與驗證 JSON 資料。
* JSON Schema 不是完整的 API 描述格式，可以用來驗證 API 描述格式的 JSON 格式有沒有寫錯。
* OpenAPI 本身也可定義資料型態，但 JSON Schema 可以進行更加完善的設定，因此 Open API 將其納入，可在 Open API 中同時使用 JSON Schemae 及 Open API。

### 以 ALPS (Application-Level Profile Semantics) 製作 API Profiles
* ALPS 是一種與 API 風格和通訊協議無關的 API 描述格式。
* 因無關於特定的風格和協議，因此**適合用於表達 API 的數位能力和訊息**，但不適合表達於需使用特定資料格式或技術的的狀況。
* 用 ALPS 的 ==設計== 表達 API 的功能，因此 API 的 ==規格== 可以是 REST、gRPC、GraphQL 等等，而 ALPS ==本身的撰寫== 可以用 XML、Json、Yaml 等等格式。
* 因 ALPS 本身包含 ==資料(訊息)== 及 ==轉換(操作)==，返回當前 API 的資訊，並且提供基於當前使用者的資訊所能延伸使用的頁面轉換或操作。

### APIs.json
可以透過撰寫一份 APIs.json 來集合 API 底下所提供的所有功能。使用者可以根據 APIs.json 來查找自己需要的功能。

APIs.json 理論上是用 Json 進行撰寫，但也有 Yaml 的變體。

## 在文件添加範例程式
:::success
範例程式讓使用者可以方便快速地瞭解 API 的實際用法
:::

### 優先提供入門使用範例
對使用者來說，最需要的是快速認識 API，因此最好提供一個簡單的案例讓他知道可以怎麼把 API 套入到他的產品中。

越複雜的 API 會帶給使用者更多的挫折，因此我們應該簡化這段流程，最好是可以複製貼上即可使用最好。

:::info
TTFHW (Time to First Hello World)，代表產生 Hello World 的時間，以我自己來說，通常越快產生第一個可運行範例的東西會讓我越有興趣做下去，因為可以越來讓我開始進行各種亂搞的實驗XD
:::

### 用工作流程範例豐富文件內容
根據 API 所提供的商業能力來設計一個使用者可能需要的情境，讓使用者只要跟著文件的程式一步一步跑，就能讓他們實現原先使用這個 API 時所想達成的目標。


## 從 API 進化成開發者網站
API 文件是個 ==**籠統**== 的詞彙，只要可以幫助使用者瞭解 API 的任何東西都能稱之為 API 文件。

### 利用開發者網站擴大 API 採用率

我們可以透過開發者網站來進行宣傳，說服使用者來使用我們的 API

開發者網站的潛在受眾：

* 管理人員
負責尋找 API、評估 API 是否符合需求並決定是否進行採購的人 (覺得有點像提出產品採購案的人，如 CTO、CEO 等等)
* 商業與產品管理人員
根據當前需求尋找能加速產品交付的人
* 產品架構師與技術主管
負責產品規劃的人，根據上級指示的需求而尋找能實現功能的 API


### 優質開發者網站的構成要素

* 特性說明
API 的特性總覽，通常是優勢的部分，包含價格、功能等等，讓用戶能瞭解我們的特色
* 案例研究
提供目前使用我們 API 的客戶是如何在他們行業中使用我們的功能，或著是我們的 API 還能如何使用
* 入門指南
快速的讓使用者串接 API 到產品中
* 認證與授權說明
如何讓使用者申請 API Token 以及他們的授權範圍
* API 技術文件
API 的細節，通常會細到每個參數是如何被使用的以及他們所代表的意義
* 發布通知與改版紀錄
記載每個版本的差異

除了以上，開發者網站建議還要具備以下特點：
* 簡易上手
* 運行狀態顯示
可以查詢目前 API 是否是正常運行的
* 即時支援
提供即時的訊息溝通或是幫助使用者快速的進行查詢等等

## 有效的 API 文件

有效的文件代表是有針對目標受眾進行撰寫，包括開發人員及管理和評估的非開發人員

如果難以對用戶進行訪談，可以用一些模擬的情境，並根據下列問題來確保 API 是能確實提供使用者幫助的：

1. API 如何解決問題
確保文件有說明到 API 能解決那些問題以及不能解決那些問題，並透過其他人的案例來表達我們的 API 是如何解決其他人的問題
2. API 的操作各自負責什麼
應該要說明每個 API 的操作所能提供的功能及適用的情況，不該只靠一句籠統的說明就讓使用者自己去摸索相似 API 間的差異
也可以透過案例來說明 API 的用法，而情境可以透過我們之前定義的 Job Story 來找靈感
3. 該如何開始
在文件中建立導航連結，讓使用者隨時可以在閱讀的文章中找到如何從當前頁面跳轉到所需要去的地方

:::warning
我們應該要假設 API 對大部分的使用者來說都是可以無師自通的，每個人的知識水平及經驗都不相同，我們可以透過這些文件來幫助他們上手
:::

### API 文件中技術寫作者的角色

傳統的文件通常是 PDF、Word 之類的，需要對軟體的每一個細部功能有相當的瞭解，並且要對語言有深入的瞭解

技術寫作的角色經歷了轉變，有些被 UX 人員取代，透過 UX 讓操作更直覺，==降低了一些問題被提出來的機會==，進而減少文件的必要性，隨著雲端和自動化的導入，軟體的迭代速度越來越快，文件的產出速度也隨之變得更快

技術寫作者在這種情況下，他們所要扮演的角色需要貼近外界的使用者，從使用者的角度出發，也能提早檢視我們所做的東西是否符合外界所需要的價值，並提早作出改善

## 開發者網站的 MVP

MVP (Minumum Viable Product，最小可行產品) 一般是指產品，在這邊是指開發者網站 ==從0開始時== 最少該具備的東西

### 1. 產出 MVP

### 2. 持續優化
優化時機點應該是 API 改版時，但可以根據不同的急迫度去調整開發者網站的優化形式


### 3. 聚焦於成長
* 加入研究案例
* 加入入門指南
* 後臺觀察流量分析，幫助未來優化產品或開發者網站
* 將內容整合成一頁內就可完整瀏覽，幫助使用搜尋功能
* 翻譯成其他語言擴展到其他地區

## 常用的開發者網站搭建工具或框架

* SSG (Static Site Generator，靜態網站產生器)
Jekyll 或 Hugo，可以整合到 Github 版控並且發布到 Github Page 之類的，且可以用 Markdown 編輯
* SwaggerUI
可透過平常的程式撰寫自動產出成品
* MVP 範本
用網路上的 MVP 範本工具來自動產生網站

###### tags: `Web API 設計原則：API與微服務傳遞價值之道`