將 API 視為業務和策略性計畫的推動者是最近才發展的趨勢，現在組織已開始大量投資於其 API 策略。
在開發 API 策略方面進行大量投資的組織，已超越傳統的技術領導者。從金融服務到醫療保健、教育到製造業等產業，API 的採用都顯著成長。
同時，API 描述格式（例如 OpenAPI 規格 (以前稱為 Swagger 規格)）的採用也大幅增加，它為您的 API 提供一種與語言無關且人類可讀的合約，允許機器和人類都能夠剖析和理解 API 應該執行的操作。
如今，數千個組織（無論大小）都使用 OpenAPI 規格 (OAS) 來簡化開發並推動 API 的採用。在整個組織的內部和外部 API 中實作 OAS 會帶來一系列獨特的挑戰，尤其是在嘗試跨多個不同團隊擴展多個 API 專案時。
此時，擁有促進 OAS 實作的工作流程可能會很有幫助。
這本電子書的目標是介紹一個易於遵循的工作流程，以在您的組織內使用 OAS。
轉型為 API 平台
應用程式程式設計介面 (或 API) 早在 PC 發明之前就已存在，並且一直被視為技術資產。然而，在過去十年中，由於網際網路、社群媒體、電子商務和行動裝置所造成的資訊中斷，讓更多組織了解 API 作為資料和服務發佈管道的重要性。
如今，據估計公開 API 的數量約為 50,000 個。這還不包括成千上萬個私有管理的內部 API，這些 API 繼續在全球主要產業中得到採用。根據 SmartBear 的 2016 年 API 狀態報告，五分之一的 API 提供者僅在過去五年內才開始開發 API。
隨著連網裝置數量呈指數級增長，API 的採用只會增加。物聯網革命也正在發生，家用裝置、機器人和穿戴式裝置都在促使我們越來越渴望保持連線。據估計，到 2020 年，世界上每個人平均將擁有七個裝置。
這進一步證明了組織應該開始考慮其 API 策略，因為 API 是滲透到所有這些不同平台和裝置的最佳方式。
OAS 驅動開發簡介
API 明顯朝著推動業務增長的方向發展。希望利用 API 的公司需要考慮到良好的自助式消耗，且第三方開發人員無需付出太多努力。過去，API 並不打算供很多人使用。API 是資料驅動的，旨在解決一些特殊的連線和通訊使用案例。文件很少，如果有的話，使用的規範直接遵循核心資料庫的術語，這表示除了少數人之外，沒有人能理解它們。
毋庸置疑，過去的 API 並非用於自助式消耗。以上不再適用於現代 Web API。與前代產品不同，新時代的 REST API 並非資料驅動，而是更以消費者為導向。解決實際消費者問題的精心設計的 API 才是關鍵，我們在 Dropbox、Stripe 和 eBay 等公司的 API 中看到了這種重點。現在，許多公司都要求採用基於 HTTP 標準的可重複使用介面，這些介面允許重複使用資料和功能，並為消費者需求和自助服務而建置。
導入 OpenAPI 規格 (OAS)
OpenAPI 規格 (OAS) 對於 REST 的意義，就像 WSDL 對於 SOAP 一樣。它為設計師、開發人員、測試人員和開發維運提供了一個通用框架，以建置和維護 API。將規格視為建置和實作 REST API 的一組規則。
OAS 與語言無關，並且人機皆可讀取，這表示人和電腦都可以在無需存取原始碼、其他文件或檢查網路流量的情況下，發現和理解服務的功能。例如，能夠直接從 OAS 定義自動產生互動式且美觀的 API 文件。
互動式文件已發展為稱為 Swagger UI 的特定工具。Swagger UI 允許開發團隊和最終消費者視覺化 API 的資源並與其互動，而無需手動將 API 整合和實作到他們自己的應用程式中。
將 OAS 新增至 API 的優點
- API 設計和協作的適當畫布：OAS 為您的團隊提供一個單一的焦點，讓您在開始撰寫程式碼之前協作設計 API。
- 具有完整性的可重複使用之清晰且正式的機制：OAS 定義中存在一些機制，這些機制是明確為跨常見物件重複使用和參考而設定。它們不需要撰寫定義的人解釋其含義。
- 用於自動化的適當工具：OAS 為伺服器範本產生（傳統或無伺服器）提供了適當的結構和工具。除了伺服器範本外，它還支援以幾乎所有流行的用戶端語言產生用戶端 SDK。
- 用於測試自動化和監控增強的必要資訊：您的 QA 團隊可以將 OAS 定義匯入其測試解決方案，從而減少在理解 API 操作時可能涉及的猜測工作。
OAS 在 API 生命周期中的作用
為了在當今競爭激烈的互聯商業環境中取得成功，組織必須給予其 API 程式一流的待遇，讓開發人員能夠靈活地整合到他們不斷發展的內部和外部環境中，並按照他們選擇的工作流程進行操作。
這是選擇適用於 API 生命周期管理的正確工具變得重要的主要原因。對於大多數團隊來說，具有 OAS 的 API 生命周期看起來會像這樣
OAS 驅動方法的優點
OAS 驅動的 API 開發提倡在實作任何其他生命週期操作之前，先設計 API 的定義。這表示即使在您開始建置 API 的業務邏輯之前，在您測試 API 是否有任何錯誤或缺陷之前，或任何其他生命週期功能之前，您都將設計 API 的介面，詳細說明您的 API 端點將展示的確切請求和回應。
OAS 驅動的方法帶來了一些與以消費者為中心的 API 開發方法直接相關的巨大優勢。
- 更好的開發人員體驗 (DX)：在競爭激烈的 API 生態系統中，良好的 API 消耗開發人員體驗至關重要。您實際上可以事先關注 API 消費者的需求。這讓您能夠採取以開發人員為中心的方法，並確保在與時間和其他開發方面競爭之前，以最佳方式滿足您的最終消費者需求。
- 實現獨立性：此方法減少了處理 API 的不同團隊（例如前端和後端團隊，或架構師、技術寫手和 QA）之間的依賴性。這是因為 API 的定義使不同的利害關係人了解 API 應該執行的操作，以及它如何與他們的工作職能相關。它充當 API 預期服務和其功能之間的合約，並確保它們之間更容易溝通。
- 更快上市：由於依賴性已消除，因此不同的團隊實際上可以更快且更有效率地執行其職能。團隊之間的交接過程顯著簡化，這使得您的 API 可以更快地發佈。
- 協助外部人員了解 API：先設計 API 會充當強制功能，以建置一個易於理解和使用的消費者友善 API。這也讓您的技術寫作團隊能夠從精心設計的 API 中建立出色的文件。
- 為您的 API 建立測試： 您的 OAS 定義提供了一份合約，描述當有人呼叫您的 API 時，回應的樣貌。這份合約可以被重新利用來建立測試案例。這樣可以大幅減少您的團隊測試 API 所需的設置時間。您可以透過匯入您的 API 定義來建立功能測試和負載測試。
- 產生實作程式碼和 SDK： 除了產生文件之外，OpenAPI 定義還可以用於透過建立實作程式碼和 SDK 來加速開發。API 定義檔案可以匯入許多不同的工具，例如 Swagger Codegen 和 SwaggerHub。這些工具可以產生多種不同語言的程式碼，例如 Java、Scala 和 Ruby。
- 讓您的 API 上線： 像 Amazon API Gateway、Azure、Apigee 或 Google Cloud 等 API 閘道，都會使用 API 定義來建立可運作的 API。
- 監控您的 API： 理想情況下，您希望在客戶注意到之前就發現 API 的問題。如果您將定義匯入像 Alertsite 這樣的工具，就可以自動監控 API。
對於許多組織來說，完全轉向以 OpenAPI 驅動的方法（也稱為「設計優先方法」）並非一蹴可幾。在某些情況下，團隊仍然遵循程式碼優先的方法，其中 OAS 定義是為現有的 API 而產生，該 API 已經建置完成，並且可能已經部署。程式碼優先方法是一種更傳統的 API 建置方式，在業務需求制定之後才開始開發程式碼，最終從程式碼產生文件。
如果開發人員直接從需求文件中開始撰寫 API 程式碼，他們可以更快地開始實作 API。如果您的上市策略強調速度和敏捷性是 API 專案成功的關鍵因素，這點就非常重要。程式碼優先方法中自動化更容易的事實，透過許多支援搭建伺服器程式碼、功能測試和部署自動化的函式庫，更加強化了這一點。有一些開放原始碼工具可以利用，在執行時或建置時，透過在您的 API 程式碼中添加註釋來從現有的 API 產生 OAS 定義。
您也可以利用像 Swagger Inspector 這樣的工具，讓您可以快速執行任何 API 請求、驗證其回應並產生對應的 OpenAPI 定義。使用 Swagger Inspector 來快速為現有的 REST API 產生基於 OAS 的文件，方法是呼叫每個端點並使用相關的回應來產生符合 OAS 的文件，或者將一系列的呼叫串連起來，為多個 API 端點產生完整的 OAS 文件。
大規模使用 OAS 進行 API 開發
雖然越來越多的組織將設計視為軟體開發生命週期及其 API 生命週期中的關鍵步驟，但很少有組織能夠有效地大規模設計 API。
當您在單一團隊中處理數量有限的服務時，設計會比較容易管理，而且依賴 PDF 樣式指南或 Wiki 頁面可能就足以讓所有人都保持一致。但是，當設計流程需要在多個團隊和數百甚至數千個不同的 API 中擴展時，會發生什麼事？
使用 SwaggerHub 優化您的 API 工作流程
團隊在實作 API 策略時面臨的最大挑戰之一，是確保具有不同技能和職責的不同團隊成員在 API 生命週期的正確階段參與。
其他挑戰包括
- 團隊管理和協作： 您如何跨團隊更新 OAS 定義，並為您的 API 撰寫詳細的文件？
- 版本管理： 隨著組織不斷迭代 API 的設計和文件，管理 API 多個版本的複雜性也隨之而來。組織如何有效地管理同一 API 的多個版本？
- OAS 定義的安全託管和共享： 隨著您使用 OAS 擴展 API 策略，維護一個讓團隊存取 OAS 定義的中央儲存庫變得越來越重要。團隊如何考慮安全地協調其 API 生命週期的各個方面？
- 與現有工具組同步： 您如何讓內部和外部環境與 API 的不同版本保持更新，尤其是在您的軟體和 API 開發發生在各種外部系統（如原始碼控制主機、API 管理平台和測試套件）之間時？
要解決這些挑戰，組織需要採用最佳的 API 開發工作流程，並確定必要的工具，以在 API 生命週期的所有階段（從設計和文件到測試和部署）優化該工作流程。
我們推出了 SwaggerHub 來改變團隊協作設計和撰寫 API 文件的方式。在過去的一年中，我們與數百名 SwaggerHub 用戶交談，以更好地了解他們如何在多個團隊和越來越多的 API 中擴展其設計流程。
一位用戶，CrowdFlower 的工程副總裁 Cameron Befus，分享了他從開放原始碼 Swagger 工具轉向使用 SwaggerHub 以進行更具可擴展性的 API 設計的經驗
「Crowdflower 一直以來都使用 Swagger 來定義我們的 API，而且這個過程因為有了 SwaggerHub 而變得更加容易。擁有像 Swagger 和 SwaggerHub 這樣很棒的工具，可以促進設計新服務時的協作，並且讓撰寫文件和整合測試這些服務變得更加容易，這對我們的團隊有很大的幫助。」
Bonotel 的資訊長 Scot Hastings 也分享了他為最近的 API 專案啟動新設計流程的經驗
「當我們進一步推進專案時，我們意識到需要加快流程並使其更有效率。我們希望自動產生使用者介面，並促進內部和外部團隊之間的協作，而不會出現麻煩或溝通問題......透過讓我們能夠更快地設計和開發 RESTful API，我們可以更快地推出新服務和服務更新」，Hastings 說。「這使得 SwaggerHub 成為我們軟體開發生命週期中的關鍵一環。」
像 CrowdFlower 和 Bonotel 這樣的組織，透過將 OpenAPI 標準化用於 API 設計，並採用一個可以無縫融入其 API 工作流程的工具，讓他們能夠在 SwaggerHub 上更有效地協作進行 API 設計，從而擴展了他們的 API 設計。
他們也代表了我們從成功擴展 API 設計流程的團隊中看到的一些關鍵原則。
準備好擴展您的設計流程了嗎？以下是您需要採取的幾個重要步驟
1. 讓您的團隊保持一致
良好的 API 設計依賴於參與 API 開發生命週期的所有利害關係人之間的有效協調。如果您的團隊在設計需求上沒有一致，或者如果正確的人無法獲得設計變更的必要可見性，當您嘗試擴展到少量 API 之外時，就會遇到摩擦。組織嘗試讓團隊成員在設計流程上保持一致的一種常見方法是透過像 Confluence 或 GitHub 這樣的協作工具。
但是，雖然這些工具在軟體開發生命週期中扮演著關鍵角色，但要針對管理 API 設計工作流程的特定用例進行配置可能會很複雜。
在 SwaggerHub 中，您可以建立組織並邀請團隊成員協作設計和撰寫 API 文件。每個組織可以根據其在 API 生命週期中的角色，有多個團隊。組織的擁有者可以根據團隊成員在設計流程中的參與程度，分配角色給他們並管理存取權限。深入了解 SwaggerHub 中的協作。
2. 提高設計流程的可見性
就像團隊在嘗試擴展 API 設計流程時可能面臨的一致性挑戰一樣，提高團隊可見性也是一項艱鉅的任務。通常，我們看到團隊會從開放原始碼 Swagger 工具（如 Swagger Editor 和 Swagger UI）開始他們的 API 設計之旅。
雖然這些工具提供了有效建立模型和視覺化 API 所需的功能，但它們並不是為了滿足大型 API 團隊的協作需求而建構的。如果您使用 OpenAPI 來處理您的 API 設計，您會希望為您的整個團隊提供一個中央位置來存取正在進行的不同服務設計工作。您也會希望確保在發生變更時通知正確的人，並且您不會將可見性限制在分散的電子郵件、Slack 訊息和 GitHub 工單中。
3. 減少依賴性
團隊之間的依賴性可能是阻礙想要從設計走向產生程式碼、草擬文件和撰寫測試案例的團隊的最大因素之一。團隊能夠減少依賴性的一種方式是透過 API「模擬」或虛擬化來實現更快的開發。您可以在 SwaggerHub 中建立新 API 時自動建立模擬，也可以稍後隨時手動建立模擬。
模擬有助於您在設計 API 時測試它，也就是在開發人員實作之前。此外，這種整合讓客戶端應用程式開發人員即使在後端尚未準備好時也可以開始處理他們的部分。無需編寫一行程式碼，您就可以讓 API 消費者針對模擬開發客戶端，保證響應與相容且真實的有效載荷。更重要的是，您可以使用「範例」結構直接在 OAS 定義中調整有效載荷。深入了解 SwaggerHub 中的模擬。
4. 設定並實施設計需求
公司在 API 上的投資是一項長期事業。設計標準不僅可以改進 API 的實作，還可以決定 API 的更新方式或新 API 的開發方式。一旦設定了設計指南，就可以更容易地在此基礎上建構並讓團隊開發 API，讓組織擴展其設計和開發流程。由於設計定義了客戶端和服務如何互動，因此設計上的差異會導致在服務開發階段產生混淆和額外開銷。這些不一致性只會倍增，它們的影響將在 API 生命週期中放大。
SwaggerHub 解決設計一致性問題的一種方法是透過我們內建的樣式驗證器，來檢查您的 API 定義是否符合某些描述標準。例如，您公司的指南可能要求所有屬性都指定範例。樣式驗證器可協助您自動化這些檢查。深入了解如何在 SwaggerHub 中標準化設計。
5. 提高設計的重複使用性
我們經常從使用 Swagger 工具和 OAS 來定義 API 的 API 團隊那裡聽到，在數百個 API 中定義多個端點時，設計流程可能會非常繁瑣。需要重複單獨定義每個端點可能會減慢設計流程，並導致 API 設計不一致。
這就是為什麼 SwaggerHub 將網域概念引入設計流程的原因。網域是可以多個 API 和其他網域之間共享的可重複使用元件。網域可以包含以下元件：定義、路徑項目、參數、回應。深入了解 SwaggerHub 中的設計重用。
6. 與您信任的工具整合
能夠從設計快速轉到撰寫文件、建構和部署 API，對於建立可擴展的 API 設計流程至關重要。即使是最好的設計標準，如果您在開始超越初始階段時遇到摩擦，也無法幫助您擴展 API 設計。API 供應商嘗試解決此問題的方法之一是在更適合 API 管理的工具之上建構額外的設計功能。雖然擁有一個All-in-One解決方案很棒，但也需要組織鎖定單一解決方案，當您想要引入新工具時，靈活性會大受限制。
在 SwaggerHub 中，我們採取了不同的方法 — 建構一個世界級的 API 設計平台，讓團隊將其作為 API 設計流程的「單一事實來源」，然後提供與團隊信任的工具的無縫整合，以交付出色的 API，包括：Apigee、AWS、Microsoft Azure 或 IBM API Connect 等 API 閘道、Bitbucket、GitHub 和 GitLab 等原始碼控制平台，以及用於功能測試的 SoapUI 等測試工具。
了解更多關於 SwaggerHub API 生命周期整合。
在 SwaggerHub 中優化您的工作流程
SwaggerHub 為各種規模的團隊提供彈性的方案。將您所有的 OAS 資產儲存在一個中央位置、設定和管理團隊，並在您的 API 的整個生命週期中協作。可選擇在雲端使用，或透過我們的企業解決方案安裝在您的防火牆內。
立即開始！開始您的 SwaggerHub 14 天免費試用，或直接與團隊聯繫以了解更多關於我們的企業解決方案，您可以在此安排演示。