DAY5 — 什麼！你的程式碼由文件產生，這樣不就不用補文件了嗎！？ — Docs tool 篇
被選召的 Gopher 們，從零開始探索 Golang, Istio, K8s 數碼微服務世界 — 第12屆iT邦幫忙鐵人賽
本文章同時發佈於：
文章為自己的經驗與夥伴整理的內容，設計沒有標準答案，如有可以改進的地方，請告訴我，我會盡我所能的修改，謝謝大家～大家好，繼昨天DAY04 Docker-Compose 的介紹後，我們終於有了一個開發環境，接下來要實作夠過各種 Docs tool 來建構各種文件與程式介面。
為什麼需要這些 Docs tool
文件與實作同步，為不同團隊提供一個簡潔的系統介紹，而不是遇到任何問題就
看code
以前接受了許多專案，文檔提供不完全，導致許多 API 根本不清楚作用，而是要透過看code來了解整體情境，這花費了巨量的時間。
也不是說看 code 不好，在Clean Code書中也有提到 :
code 必須要清楚表達意圖，而不是靠各種註解解決
而文件跟註解有幾分相似，是否如果 code 寫得好就不需要文件了呢？
我認為還是要的，以下是我覺得需要寫成文件的部分:
- 一連串不同 API 達成的情境: 因為單純看 code 是無法說明一整個情境的。
- API 所規範的介面: 各團隊可以根據此規範來串接 API，以避免後端說要帶 a 資料前端卻帶 b 資料的窘境。
為什麼文件往往趕不上實作？
因為寫文件的成本往往高於寫 code
我認為有以下關係:
- 當更新了 code 的功能，我們就要點開各式各樣的文件去更新
- 文件軟體用起來有夠不順手，奇怪我是程式設計的為什麼要一天到晚畫圖
- 為什麼文件寫的跟 code 不一樣，算了這個文件不看白不看，還是看 code
所以我已以下原則來寫文件，我認為可以減低以上問題的成本 XD:
- 統一都用 Markdown 來寫，流程圖與關係圖用mermaid-js與vscode-drawio一次解決
- 因為採用 Markdown 所以不用再
為了邏輯而畫圖，而是寫好邏輯就自動產生圖 - 用swagger-generator來產生程式介面，再來開發，這樣就可以
用文件產生程式介面。
用文件產生程式介面？！
沒錯！你可以這樣做，在 GraphQL 問世後，大家慢慢發現可以這樣做，要更改程式嗎？那請先更新 GraphQL schema，如此一來文件永遠不會落後，前後端的 code 也可以透過這個文件產生。
而 gRPC 也是有同樣的概念在裡頭，gRPC 是透過定義好 Protobuf 文件來產生程式碼。
但較少人知道，Restful API 其實也是可以這樣做的，即是定義好 Open API，並透過上述swagger-generator來產生程式碼。
Docs tool 介紹
- mermaid-js: 提供用簡單的 Markdown 來撰寫流程圖的功能
- vscode-drawio: 可以讓 vscode 可以直接在
.jpg/.png中編輯圖片並同步更新在 Markdown 中 - swagger-generator: swagger是一個撰寫 Open API 介面的方案，大家常常拿它來撰寫介面，但其實他也可以透過這些文件來生產出
不同語言的Server端與Client端，對於規範好不同團隊語言的接口很方便。 - Insomnia Designer: 可以用 Open API 來產生 Postman 測試端點的軟體！
開始來基於 Digimon-Service 來撰寫文件～
還記得小時候玩的數碼育成機嗎？一開始會有一顆數碼蛋，我們要慢慢培育他，隨著時間這顆數碼蛋就會孵化出數碼獸，並與我們一起成長。Digimon-Service 希望可以提供這些功能。
所以基於這些需求，我們開始把文件撰寫出來～
實作我們採用 Restful API，以下是 API — 使用Insomnia Designer完成:
Insomnia Designer的設計介面非常友好，並且！當你點了上方的DEBUG
他竟人產生了測試端點！連端點都不用慢慢加了，太神啦～！
流程上如下 — 使用mermaid-js完成:
產生數碼蛋
培育數碼獸
查看數碼獸
總結
有了這些便捷的工具後，
文件就不是個很
花費時間又重工的事情了，而是可以直接使用在開發上的好幫手！
接下來要介紹如何透過swagger-generator生產出 Golang Server 的介面並且透過 Clean Architecture 來實作，並透過Insomnia Designer測試
Write Medium in Markdown? Try Markdium!
