OpenAPI 仕様 (OAS) は、HTTP API の標準的で言語に依存しないインターフェースを定義します。これにより、人間もコンピューターも、ソースコード、ドキュメント、またはネットワークトラフィックの検査にアクセスすることなく、サービスの機能を検出して理解できます。適切に定義されていれば、コンシューマーは最小限の実装ロジックでリモートサービスを理解し、操作できます。
OpenAPI 定義は、ドキュメント生成ツールで API を表示したり、コード生成ツールでさまざまなプログラミング言語のサーバーやクライアントを生成したり、テストツールなどで使用したりできます。
OpenAPI とは何かという上記の記述は、その仕様から直接引用しました。Swagger Editor で OpenAPI 定義を手作業で記述する方のために、この記事が書かれました。
数年前、私は Ubiquiti Inc という会社で働いていました。私たちは組み込み UI を備えた優れたワイヤレスハードウェアソリューションを製造していました。私は、UNMS と呼ばれるクロスハードウェア構成システムが設計および開発されていた時期に、この会社に入社できたことを幸運に思っています。システムのバックエンド部分は、フロントエンド層が消費する巨大な REST API 層で構成されていました。私たちは API を作成するために デザインファーストのアプローチ を使用しました。
このアプローチのワークフローは次のステップで構成されています。
- Swagger Editor を使用して OpenAPI 2.0 定義に変更を加える
- 発行者: チームが新しい API エンドポイントがどのように見えるかを確認するために GitHub プルリクエスト を発行する
- レビュー担当者: プルリクエストの OpenAPI 定義を Swagger Editor に貼り付けて、エラーが導入されていないか確認する
- プルリクエストをマージする
- OpenAPI 定義で定義された実際の REST API を実装する
今日なら、このワークフローを自動化し、継続的インテグレーション に作業を任せる方法をすぐに考えるでしょう。残念ながら、当時私の CI/CD パイプラインに関する知識は限られており、CI/CD が提供する利点と価値を完全に認識していませんでした。
それ以来、しばらく時間が経ちました。私は宿題をして、CI/CD のトピックを徹底的に勉強しました。私は GitHub Actions と自動化の大ファンになりました。GitHub Actions を使用して、上記のワークフローを自動化してみましょう。
技術設計
Swagger Editor を使用して、そのアクションへのパラメータとして提供される OpenAPI 定義を検証する GitHub Action を作成する必要があります。
GitHub Action で Swagger Editor を使用するには、2 つの方法があります。swaggerapi/swagger-editor イメージを使用して Docker コンテナで実行するか、https://editor.swagger.io/ を直接使用するかです。Swagger Editor が実行されたら、Puppeteer を使用して Chromium ブラウザのヘッドレスバージョンを開き、OpenAPI 定義を Swagger Editor に貼り付け、エラーがレンダリングされるのを待ちます（定義が有効であれば、エラーはレンダリングされません）。Puppeteer を使用して Swagger Editor からエラーを読み取り、GitHub Actions API を介してそれらを表現します。GitHub Action は、エラーがあれば失敗を報告し、ドキュメントが有効でエラーが含まれていない場合は成功を報告します。
JSON Schema の検証だけでなく、なぜ Swagger Editor を使用するのか？Swagger Editor は、JSON Schema の検証に加えて、独自のエラー認識レイヤーを追加します。残念ながら、この追加レイヤーは Swagger Editor のコードと密接に結合しており、最も簡単な使用方法は、ブラウザで Swagger Editor を実行することです。
実装
実装は思ったほど簡単ではありませんでした。しかし、私は以前に述べた技術設計とそのすべての要件に沿って、この GitHub Action を実装することができました。私はそれを swagger-editor-validate と名付けました。
使用方法
この GitHub Action を使用する方法は主に2つありますが、どちらも定義ファイルが 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: https:///
definition-file: examples/openapi-2-0.yaml
OpenAPI 定義が正常に検証された場合に表示される内容です。
OpenAPI 定義にエラーが含まれている場合に表示される内容です。
今後
実装中に、このアクションが恩恵を受けるであろう他の機能を特定しました。最初のバージョンの実装範囲を広げないために、これらの機能を実装せず、文書化して後で実装することにしました。これらの機能には次のものがあります。
最も興味深いのは、エラーを無視するメカニズムだと思います。https://editor.swagger.io/ で検証すると、OpenAPI 定義にエラーが含まれていることは非常によくあります。これらのエラーに対して作成者が何もできない場合や、これらのエラーが既知で無視される場合があります。これにより、このようなユースケースへの扉が開かれ、これはかなり一般的であると確信しています。
swagger-editor-validate が、Swagger Editor を使用して OpenAPI 定義を編集するすべての人にとって便利なツールになることを願っています。Ubiquiti Inc の私の古いチームにとっても便利になることはわかっています ;]