| 閱文時長 | | 3.92分鍾 | 字數統計 | | 2754.05字符 |
| 主要內容 | | 1、什么是API文檔 2、API文檔的使用 3、聲明與參考資料 | ||
| 『微服務·API文檔』 | |||
| 編寫人 | | SCscHero | 編寫時間 | | Thursday, December 3, 2020 |
| 文章類型 | | 系列 | 完成度 | | 待完善 |
| 座右銘 | 每一個偉大的事業，都有一個微不足道的開始。Hello World！ | ||
一、什么是API文檔 完成度：100%
a) 廣泛定義
由於在各個百科網站上沒有給出准確定義，但不少大佬給了定義，以下是Keshav Vasudevan[1]給出的定義。
1.API文檔，它為什么重要?
我們處在一個多平台的經濟環境中，而api是數字環境的粘合劑。平台是用戶可以為其他用戶擴展的產品。任何產品都可以通過為用戶提供在其上添加服務和功能的方法成為平台。api是平台經濟的推動者，允許用戶在現有產品上增強和添加服務。當一個產品轉變為一個平台時，它就有了一種新的用戶類型:第三方開發人員。迎合開發商的需求是很棘手的。他們善於分析、精確，並試圖解決API的重要問題。他們希望了解如何有效地使用API，這就是API文檔的作用所在。
2.什么是API文檔?
API文檔是可交付的技術內容，包含關於如何有效地使用和集成API的說明。它是一個簡明的參考手冊，包含使用API所需的所有信息，以及關於函數、類、返回類型、參數等的詳細信息，並支持教程和示例。API文檔傳統上是使用常規的內容創建和維護工具以及文本編輯器完成的。像OpenAPI/Swagger規范這樣的API描述格式已經自動化了文檔處理過程，使得團隊更容易生成和維護文檔。第三方開發人員是API的主要消費者，他們正忙於解決復雜的編程難題。對於技術用戶來說，您的API是一種達到目的的手段，他們希望盡可能快地集成以推進軟件開發，這意味着他們應該立即了解您的API的價值和用途。開發人員在發現、學習使用以及最終與API集成時積累的經驗稱為開發人員體驗(DX[2])。API文檔是一個高評級DX的關鍵。
3. 為什么使用API文檔？
在API生命周期的所有階段中，文檔可能是增長最快的領域。對於圍繞文檔的工具生態系統來說，這一點尤其正確。注意到這種趨勢很有趣，因為文檔通常是開發人員在啟動代碼時很少關注的東西。事實上，實現代碼要比編寫好的文檔容易得多。但這是因為它對采用和使用的直接影響。你可以擁有最好的，功能性的產品，但如果不知道如何使用，沒有人會去使用它。文檔是良好開發人員體驗的基礎。----來自《Swagger官網》[3]
b) 個人理解
我對API文檔理解是一個交付性成果，主要應用於前后端分離開發或者第三方API調用，並能增強API可維護性及可用性。在早前項目中（大概是2019年下半年），我們的項目就應用了Swagger，那時候只是簡單使用，生成API文檔，並苛求了自己寫注釋的習慣。對於其他功能，比如：API分組、自定義參數、Swagger導入Postman、分布式系統中網關集成文檔，沒有深入學習。因此，有了這篇博客總結沉淀一下。
二、API文檔的使用 完成度：100%
a) 微服務下的API文檔
單體架構下的API文檔自然不必多說。但在分布式系統下的API文檔，是否有所不同呢。此時我們需要了解微服務架構中的一個組件--API網關。我們需要將不同服務的API文檔自動整合到一個項目中，這個項目可以是API網關，也可以是一個獨立API文檔管理系統（由任務調度器自動獲取下游API數據，更新此系統）。
作為.Neter，博主會寫一篇關於".NetCore3.1框架集成Ocelot+Swagger組件"的博客。
b) 常用的API文檔組件
- Swagger：開源；易上手；輕量級；RESTful風格；嵌入項目自動生成；UI簡潔漂亮；不能保存參數；支持數據導出；適合前后端分離開發人員使用。
- YApi：開源；權限管理；支持Swagger、Postman等數據導入；已有大企業使用中；維護麻煩（但有解決方案）；適合大規模團隊使用。
- Postman：保存在Collection的API集合可生成API文檔。可以更改此文檔為開放文檔或私有賬號文檔；功能有局限性；但可保存參數；適合測試人員使用。
總結：博主用過Swagger和Postman的API文檔。覺得兩者結合使用可以滿足大部分需求。YApi體驗過，感覺還可以，權限功能比較實用，也因此受到了大企業的青睞。
三、聲明與參考資料 完成度：100%
原創博文，未經許可請勿轉載。
如有幫助，歡迎點贊、收藏、關注。如有問題，請評論留言！如需與博主聯系的，直接博客私信SCscHero即可。
Keshav是技術領域公認的產品和市場領導者，對建立和發展基於SaaS的網絡和移動應用程序充滿熱情。主導SmartBear軟件兩款成功SaaS產品的產品管理。幫助SwaggerHub的產品線增長了200%，並將其打造成了數百萬美元的資產。專業領域包括產品管理、市場營銷和數據分析，並傾向於將產品從測試版增長到規模化。有扎實的定量研究背景，了解大型復雜數據集的工作。獲得 MEM 學位。技能：Adobe SiteCatalyst (Omniture)，Mixpanel, MS Office, XLMiner, Solver, HTML/CSS, JQuery, AJAX, Spotfire, JIRA, Adobe Photoshop, Swagger/OpenAPI規范，Ruby on Rails，谷歌分析，SEO優化，敏捷的產品管理。 ↩︎
DX是代表了API的理想開發體驗的評級。數字越高，分數越高，10代表完美。該指數包括13個獨立的標准，每個標准根據重要性進行加權。其中最重要的因素是:在主流語言中使用的庫；深入淺出的入門指南；自助解決方案(不需要"演示"或"呼叫我們")；清晰的定價，讓開發者知道它的成本； ↩︎