OpenAPI 規格 (OAS) 定義了一個與語言無關的 HTTP API 標準介面。這讓人類和電腦都能在不存取原始碼、文件或透過網路流量檢查的情況下，探索和理解服務的功能。當定義正確時，使用者可以用最少的實作邏輯來理解和與遠端服務互動。
然後，文件產生工具可以使用 OpenAPI 定義來顯示 API，程式碼產生工具可以產生伺服器和各種程式語言的用戶端、測試工具和許多其他用例。
我直接從 OpenAPI 的規格中取得上述關於 OpenAPI 是什麼的描述。如果您是使用 Swagger Editor 手動撰寫 OpenAPI 定義的人，那麼這篇文章就是為您而寫的。
幾年前，我曾在一家名為 Ubiquiti Inc 的公司工作。我們正在生產具有內嵌 UI 的優良無線硬體解決方案。我很幸運能夠在一個名為 UNMS 的跨硬體配置系統正在架構和開發時加入這家公司。該系統的後端部分包含一個龐大的 REST API 層，前端層正在使用它。我們採用了設計優先方法來產生 API。
此方法的工作流程包含以下步驟
- 使用 Swagger Editor 在 OpenAPI 2.0 定義中建立變更
- 發行者：發出一個 GitHub Pull Request，供團隊檢閱新 API 端點的外觀
- 審閱者：將 Pull Request 中的 OpenAPI 定義貼到 Swagger Editor 中，以查看是否引入錯誤
- 合併 Pull Request
- 實作 OpenAPI 定義中定義的實際 REST API
今天我會立即考慮如何自動化此工作流程，並讓持續整合為我們完成工作。不幸的是，當時我對 CI/CD 管線的知識有限，我並未完全了解 CI/CD 提供的優點和價值。
從那時起過了一段時間。我做了功課，並徹底研究了 CI/CD 主題。我成了 GitHub Actions 和自動化的忠實粉絲。讓我們嘗試使用 GitHub Actions 自動化上述工作流程。
技術設計
我們需要產生一個 GitHub Action，使用 Swagger Editor 來驗證作為參數提供給該 Action 的 OpenAPI 定義。
在 GitHub Action 中使用 Swagger Editor 可以透過兩種方式達成：使用 swaggerapi/swagger-editor 映像在 Docker 容器中執行它，或直接使用 https://editor.swagger.io/。現在我們已經執行 Swagger Editor，我們可以使用 Puppeteer 開啟 Chromium 瀏覽器的無頭版本，將 OpenAPI 定義貼到 Swagger Editor 中，並等待它呈現錯誤（如果定義有效，則不會呈現錯誤）。使用 Puppeteer 從 Swagger Editor 讀取錯誤，並透過 GitHub Actions API 呈現它們。如果文件有效且不包含錯誤，GitHub Action 將會回報成功，如果存在任何錯誤則會回報失敗。
為什麼使用 Swagger Editor 而不只是 JSON Schema 驗證？嗯，Swagger Editor 會在 JSON Schema 驗證之上增加它自己的額外錯誤識別層。不幸的是，這個額外層與 Swagger Editor 程式碼緊密耦合，而使用它的最簡單方法是透過在瀏覽器中執行 Swagger Editor 來使用它。
實作
實作不如我預期的那麼直接。但我仍然成功根據先前提及的技術設計，實作了這個 GitHub Action，並滿足其所有要求。我將其命名為 swagger-editor-validate。
用法
如何使用此 GitHub Action 有兩個主要用例，但它們都利用了您的定義檔案存在於您的 GitHub 儲存庫中的事實。您只需要提供檔案系統路徑即可。
公開用例
如果您可以存取網際網路，並且不介意此 GitHub Action 將您的 OpenAPI 定義傳送至 https://editor.swagger.io/ 進行驗證，則請使用此工作流程。
on: [push]
jobs:
test_swagger_editor_validator_remote:
runs-on: ubuntu-latest
name: Swagger Editor Validator Remote
steps:
- uses: actions/checkout@v2
- name: Validate OpenAPI definition
uses: char0n/swagger-editor-validate@v1
with:
definition-file: examples/openapi-2-0.yaml
私人用例
如果您想要保持完全的隱私，而且您的 OpenAPI 定義可能包含敏感資訊，請使用以下工作流程。該工作流程使用作為工作流程服務執行的 Swagger-editor Docker 映像。
on: [push]
jobs:
test_swagger_editor_validator_service:
runs-on: ubuntu-latest
name: Swagger Editor Validator Service
# Service containers to run with `runner-job`
services:
# Label used to access the service container
swagger-editor:
# Docker Hub image
image: swaggerapi/swagger-editor
ports:
# Maps port 8080 on service container to the host 80
- 80:8080
steps:
- uses: actions/checkout@v2
- name: Validate OpenAPI definition
uses: char0n/swagger-editor-validate@v1
with:
swagger-editor-url: http://localhost/
definition-file: examples/openapi-2-0.yaml
如果您的 OpenAPI 定義驗證成功，您會看到這個。
如果您的 OpenAPI 定義包含錯誤，您會看到這個。
未來
在實作過程中，我確定了此 Action 可以從中受益的其他功能。為了不擴展第一個版本的實作範圍，我決定不實作這些功能，而是記錄它們並稍後再實作。這些功能包括
我認為最有趣的是忽略錯誤的機制。當在 https://editor.swagger.io/ 中驗證時，OpenAPI 定義包含錯誤是很常見的。在某些情況下，作者無法處理這些錯誤，並且這些錯誤是已知且會被忽略的。這將為此類用例開啟大門，我確信這很常見。
我希望 swagger-editor-validate 將成為任何使用 Swagger Editor 編輯 OpenAPI 定義的人的方便工具。我知道它將會對我在 Ubiquiti Inc 的舊團隊很方便；]