什麼！你的程式碼由文件產生，這樣不就不用補文件了嗎！？ - Docs tool 篇

• Github(包含程式碼)

• Medium

• iT 邦幫忙

文章為自己的經驗與夥伴整理的內容，設計沒有標準答案，如有可以改進的地方，請告訴我，我會盡我所能的修改，謝謝大家～

為什麼需要這些 Docs tool

文件與實作同步，為不同團隊提供一個簡潔的系統介紹，而不是遇到任何問題就看code

code 必須要清楚表達意圖，而不是靠各種註解解決

• 一連串不同 API 達成的情境: 因為單純看 code 是無法說明一整個情境的。

• API 所規範的介面: 各團隊可以根據此規範來串接 API，以避免後端說要帶 a 資料前端卻帶 b 資料的窘境。

為什麼文件往往趕不上實作？

因為寫文件的成本往往高於寫 code

1. 當更新了 code 的功能，我們就要點開各式各樣的文件去更新

2. 文件軟體用起來有夠不順手，奇怪我是程式設計的為什麼要一天到晚畫圖

3. 為什麼文件寫的跟 code 不一樣，算了這個文件不看白不看，還是看 code

1. 統一都用 Markdown 來寫，流程圖與關係圖用mermaid-js與vscode-drawio一次解決

2. 因為採用 Markdown 所以不用再為了邏輯而畫圖，而是寫好邏輯就自動產生圖

3. 用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 來撰寫文件～

• 提供一個數碼蛋，讓 client 端可以領取。

• 數碼蛋會隨著時間孵化。

# swagger.yamlopenapi: 3.0.1info:  title: Digimon Service API  description: 提供孵化數碼蛋與培育等數碼寶貝養成服務  version: 1.0.0servers:  - url: http://localhost:5000/api/v1paths:  /digimons:    post:      summary: 產生數碼蛋      description: 產生一顆數碼蛋，供request端養成      requestBody:        description: 客製數碼蛋的請求        required: true        content:          application/json:            schema:              $ref: "#/components/schemas/DigimonInfoRequest"      responses:        "200":          description: 數碼蛋的資訊          content:            application/json:              schema:                $ref: "#/components/schemas/DigimonInfo"        "500":          $ref: "#/components/responses/500InternalError"  /digimons/{digimonID}:    get:      summary: 查看數碼獸狀態      parameters:        - in: path          name: digimonID          schema:            type: string          required: true          description: 數碼蛋的唯一識別碼，格式為uuid v4      responses:        "200":          description: 數碼蛋的資訊          content:            application/json:              schema:                $ref: "#/components/schemas/DigimonInfo"        "500":          $ref: "#/components/responses/500InternalError"  /digimons/{digimonID}:foster:    post:      summary: 培育數碼獸      description: 對數碼獸進行培育，以改善數碼獸的狀態      parameters:        - in: path          name: digimonID          schema:            type: string          required: true          description: 數碼蛋的唯一識別碼，格式為uuid v4      requestBody:        description: 培育的食物        required: true        content:          application/json:            schema:              $ref: "#/components/schemas/FosterRequest"      responses:        "200":          description: 培育完畢後的數碼獸的資訊          content:            application/json:              schema:                $ref: "#/components/schemas/DigimonInfo"        "500":          $ref: "#/components/responses/500InternalError"components:  schemas:    DigimonInfo:      type: object      properties:        id:          type: string          description: 數碼蛋的唯一識別碼，格式為uuid v4          example: 56e400bd-c98b-49b9-ad8c-0607800e026f        name:          type: string          description: 數碼蛋的名稱          example: Agumon        status:          type: string          description: 數碼蛋此時的狀態          example: healthy    FosterRequest:      type: object      properties:        food:          type: object          description: 培育所使用的食物          properties:            name:              type: string              description: 食物名稱              example: apple    DigimonInfoRequest:      type: object      properties:        name:          type: string          description: 數碼蛋的名字      required:        - name      example:        name: Agumon    Error:      type: object      properties:        message:          type: string          description: 錯誤訊息        code:          type: number          description: >            錯誤代碼:
             * `3000` - Internal error
      required:        - message        - code      example:        message: "Internal error. Parsing failed"        code: 3000  responses:    500InternalError:      description: 伺服器錯誤      content:        application/json:          schema:            $ref: "#/components/schemas/Error"

• Digimons: 紀錄數碼獸狀態

• Diets: 紀錄數碼獸飲食

總結

文件就不是個很花費時間又重工的事情了，而是可以直接使用在開發上的好幫手！

參考

• 2019 Bandai 20th Anniversary Digimon Virtual Pet Unboxing & Review [4K UHD]