| 閱文時長 | | 3.92分鐘 | 字數統計 | | 2756.9字符 |
| 『微服務·API文檔』 | |||
| 編寫人 | | SCscHero | 編寫時間 | | Thursday, September 10, 2020 |
| 文章類型 | | 系列 | 完成度 | | 待完善 |
| 座右銘 | 每個偉大的事業，都有一個微不足道的開始。Hello World！ | ||
因爲在各個百科網站上沒有給出準肯定義，但很多大佬給了定義，如下是Keshav Vasudevan[1]給出的定義。html
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]
我對API文檔理解是一個交付性成果，主要應用於先後端分離開發或者第三方API調用，並能加強API可維護性及可用性。在早前項目中（大概是2019年下半年），咱們的項目就應用了Swagger，那時候只是簡單使用，生成API文檔，並苛求了本身寫註釋的習慣。對於其餘功能，好比：API分組、自定義參數、Swagger導入Postman、分佈式系統中網關集成文檔，沒有深刻學習。所以，有了這篇博客總結沉澱一下。後端
單體架構下的API文檔天然沒必要多說。但在分佈式系統下的API文檔，是否有所不一樣呢。此時咱們須要瞭解微服務架構中的一個組件--API網關。咱們須要將不一樣服務的API文檔自動整合到一個項目中，這個項目能夠是API網關，也能夠是一個獨立API文檔管理系統（由任務調度器自動獲取下游API數據，更新此係統）。api
總結：博主用過Swagger和Postman的API文檔。以爲二者結合使用能夠知足大部分需求。YApi體驗過，感受還能夠，權限功能比較實用，也所以受到了大企業的青睞。網絡
原創博文，未經許可請勿轉載。
若有幫助，歡迎點贊、收藏、關注。若有問題，請評論留言！如需與博主聯繫的，直接博客私信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個獨立的標準，每一個標準根據重要性進行加權。其中最重要的因素是:在主流語言中使用的庫；深刻淺出的入門指南；自助解決方案(不須要"演示"或"呼叫咱們")；清晰的訂價，讓開發者知道它的成本； ↩︎前後端分離
Swagger官方文檔 ↩︎編輯器