系統架構系列 - 6: 軟體工程文件

這次我們來介紹一個在軟體工程中相對容易被忽略，但其實在多人協作中很重要的環節——「文件」。軟體的文件有很多種類，例如 API 文件、UML文件。

API 文件

近幾年軟體快速更迭，使得 API 的內容（如參數或回傳類別）時常更改，因此API 文件應與程式碼一同納入版本控制機制。在可以納入版本控制的前提下，YAML 和 Markdown 成為大多數人的選擇。

YAML & Swagger

YAML（YAML Ain't Markup Language）是一種人類可讀的資料序列化格式，與 JSON 類似，都是透過標準化格式進行配置與資料交換。由於 YAML 支援多種資料類型，因此在 Docker、Kubernetes 等領域被廣泛應用。

在 API 文件方面，我們普遍使用 Swagger 工具（現已更名為 OpenAPI Specification）來協助閱讀 YAML 檔案的內容[註1]。可以在線上使用 Swagger 的網站：Swagger Editor。

Markdown

Markdown 是許多軟體工程師熟悉的工具，畢竟每個專案（應該）都有 README 文件，而這份文件通常是用 Markdown 撰寫的。除了基本的標題、粗體、列表等格式外，Markdown 還能製作表格，甚至可以用來繪製流程圖。範例如下：

```mermaid
flowchart LR
  A --> B
```

其他更詳細的資訊請參考：Mermaid User Guide | Mermaid

UML 文件

UML（Unified Modeling Language）是一種標準化建模語言，旨在幫助不同專案和部門的人員在開發過程中協作。UML 包含多種類型的圖表，例如狀態圖、時序圖等。

舉例來說，當開發 API 時，為了確認從使用者開始使用到接收回覆的整個流程，可以使用時序圖來確認每個步驟的 if-else 判定以及大約所需的時間等細節，這樣可以幫助開發人員和 PM 更好地了解整個流程。

對我個人而言，我非常喜歡使用 PlantUML 這個工具來繪製 UML 圖。PlantUML 本身是一個開源工具，使用的文字語法相對簡單，並且支援多種圖表類型，這在實務上非常方便。

[註1] 在一般軟體開發流程中，我們可以直接在 CI/CD 步驟中使用 Redocly 套件，將各個 API 的 YAML 檔案統整成一個文件。

參考資料

1. https://zh.wikipedia.org/zh-tw/YAML
2. https://aws.amazon.com/tw/compare/the-difference-between-yaml-and-json/
3. https://editor.swagger.io/
4. https://github.com/Redocly/redoc
5. https://mermaid.js.org/intro/getting-started.html
6. https://zh.wikipedia.org/zh-tw/统一建模语言
7. https://ithelp.ithome.com.tw/articles/10261018
8. https://plantuml.com/zh/