SmartBear Connect 2020 まとめ: SwaggerHub レジストリ API を使用して CI/CD 統合を合理化する

今年の SmartBear Connect 2020 バーチャル イベントでは、素晴らしい 1 週間を過ごすことができました。セッションの合間にホールで皆さんにお会いすることはありませんでしたが、孤独なホーム オフィスからいくつかの Slack メッセージを交換しました。

今回のイベントでは、いくつかの優れたセッションがありましたが、API 開発者の皆さんには、API 設計のプロダクト マネジメント ディレクターである Stephen Mizell 氏によるセッションをぜひご覧いただきたいと思います。セッションのタイトルは「SwaggerHub レジストリ API を使用して CI/CD 統合を合理化する」です。バーチャル セッションは、具体的には次の 5 つのセクションで構成されていました。

  • DevOps、CI/CD、および Git のワークフロー
  • SwaggerHub 統合によって解決される問題
  • これらの問題に対処しない場合のビジネスへの影響
  • これらの問題に対する可能な解決策
  • SwaggerHub ワークフローのデモ

はじめに

最初のセクションでは、DevOps とは何か、継続的インテグレーションと継続的デリバリー (CI/CD) はどのように適用されるのか、そしてこの 2 つの分野が Git とどのように交わるのかを、一歩下がって検討します。そして、この 2 つの分野と Git、さらには他のソース コントロール管理ツールとの接点を考察します。

では、DevOps とは何か。業界調査会社の Gartner 社は、DevOps を「システム指向のアプローチの中で、アジャイルで無駄のないプラクティスを採用することにより、迅速な IT サービスの提供に焦点を当てた、IT 文化の変化。」と定義しています。または別の見方をすれば、「DevOps は人 (および文化) を重視し、運用チームと開発チームのコラボレーションを向上させようとするものである。」ということになります。

CI/CD は、DevOps と同様に、コードのビルド、テスト、デプロイに使用されるツールとプロセスの両方を具体化したものです。CI/CD は、アプリケーション開発チームがコードの変更をより頻繁に、より高い品質で提供できるようにするためのパイプラインと考えてください。

このイントロダクションで扱う最後のトピックは、Git リポジトリとの対話、特にワークフローに関するものです。今日のソフトウェア開発は、開発者がプロジェクトのさまざまな部分で並行して作業する共同作業であり、Git のようなソース コード管理ツールを使用して、複数のワークフローにまたがる変更を管理および追跡します。

API 設計で直面する共通の問題

次のセクションでは、組織が API 開発で直面する問題に焦点を当てます。

プレゼンテーションで指摘されたように、これは、API 開発と API ドキュメント作成という 2 つのプロセスが切り離されている場合に起こります。

  1. 「デプロイされた API とドキュメントが同期していない。」
    API 設計から始め、変更を提案することはあっても、コード開発プロセスの中で変更を利用することは、手動のステップになります。API 設計そのものを開発プロセスに利用するのではなく、見たものに沿って開発するという試みです。

  2. 「開発を推進するためにAPI 設計を使用していない。」
    組織によっては、API 設計と開発を推進するためにデザイン ファーストを活用する代わりに、コード ファーストというアプローチを採用しているところもあります。開発チームはまず何をすべきかを決定し、次にその変更を実装するためのコードを書き、そのコードから OpenAPI ドキュメントを作成します。Stephen が指摘するように、問題はそのドキュメントが公開されなかったり、API 設計や定義のために一般的でない場所に公開されることです。

  3. 「コードファーストだが、OpenAPI をどこにも公開していない。」
    これは、チームが直面する共通の問題です。API に変更が加えられたり、新しいバージョンが作成されたりすると、どの API が本番環境に反映されたのかを知ることが難しくなる可能性があります。

  4. 「API のどのバージョンが本番環境にあるかわからない。」
    プレゼンテーションで指摘されたように、これらの問題は、API の設計がある場所で行われ、CI/CD 駆動型ソフトウェア開発が別の場所で行われる場合に発生します。

想定されるビジネスへの影響

この SwaggerHub プレゼンテーションの次のセクションでは、API 設計が CI/CD パイプラインと整合していない場合に組織が直面する影響について説明します。1 つ目は、おそらく最も明白な問題である、API ユーザーのフラストレーションに関するものです。ドキュメントが不完全であり、API の動作と一致しない場合、API ユーザーはフラストレーションを感じ、API の使用を躊躇し、組織に対する信頼性が損なわれる可能性があります。次に、API 設計を開発に生かさなければ、企業は開発者がビジネスの目標に合わないものを作ってしまう危険性があります。3 つ目は、開発者は自分では正しい道を進んでいると思っていても、最終的には当初の設計を満たさないものを作ってしまうかもしれません。最後に、API 設計に関して断絶が生じるのは、API の発見性に関わる場合です。OpenAPI のドキュメントが中央に公開されていないと、他のチームがそれを見つけることができず、重複や API の不整合が生じる可能性があります。

問題解決のために可能なこと

この時点でトピックは、API 設計とソフトウェアの開発および提供を統合する際に、組織が目指すべき理想的な未来の状態についての議論に移ります。目指すべき状態のキーポイントは次のとおりです。

  • API テストは自動化され、API 設計を活用している
  • デザインツール、CI/CD、およびドキュメントが連携し、統合されている
  • ツールやサービスを問わず、Git のワークフローを同じにする
  • API 設計に基づいて API を検証する
  • ドキュメントが最新の API デプロイメントに対応している

SwaggerHub と CI/CD

そのような状態になるまで組織を加速させるためには、SwaggerHub のようなツールを CI/CD パイプラインの仲介役として活用するのが一つの方法です。

SwaggerHub には、Git (GitHub、GitLab、Bitbucket、およびほとんどのソース コントロール管理ツールやビルド ツール) の統合機能が組み込まれています。API に変更が生じるとすぐに、SwaggerHub はその変更を Git リポジトリに反映することができます。

  1. Git リポジトリに SwaggerHub の統合機能を搭載
    チームが独立して作業を行う場合、新しいバージョンを作成することで、SwaggerHub から直接ブランチを作成することができます。そして、そのバージョンに関連するすべての変更は、バージョンごとのブランチに反映されます。

  2. 提案された変更は、Git リポジトリにそれぞれのブランチを作成
    SwaggerHub は、唯一の信頼できるソースとして機能し、API 設計を CI/CD パイプラインに反映し、CI/CD パイプラインは同じ API 設計を活用することができます。

  3. API の検証は、CI/CD パイプラインで行われる
    この機能により、開発者は CI/CD ワークフローの自動化と効率化を図ることができます。レジストリ API を利用して、SwaggerHub レジストリ内の OpenAPI 定義の統合、検索、取得、作成、および更新を行います。

  4. CI/CD は、SwaggerHub Registry API を使用して、デフォルトの保存、更新、公開、マークを行う

SwaggerHub のデモと CI/CD パイプラインの効率化

プレゼンテーションのこの時点で、スライドから SwaggerHub のデモに移行し、CI/CD パイプラインをどのようにサポートするかを紹介します。デモのセクションは、12:36 から始まり、Stephen がワークフローの概要を説明しながらデモの準備をします。

  • SwaggerHub 内で API 変更を提案する
  • 変更点を GitHub に反映させる
  • ビルドの失敗を認識する
  • OpenAPI を参考にした新しいコードを作成する
  • プル リクエストを作成し、マスターへマージする
  • 最終ビルドを開始し、テストを通過する
  • API ドキュメントを SwaggerHub に公開し、デフォルトとしてマークする

デモ (@14:48) では、Stephen が OpenAPI Spec を使って作成した API (Book API) を紹介し、SwaggerHub の統合機能を使用して、Git でどのように設定したかを説明しています。デモは上記のワーク フローに沿って進められます。数分かけて、ご自身でご覧ください。SwaggerHub によって Git との統合に加えられる効率性と自動化されることに感銘を受けると思います。

SwaggerHub を実際に体験してみよう

さらに一歩進んでみたいという方は、SwaggerHub の無料試用版をダウンロードしてください。SwaggerHub の機能を Git で体験するには、これ以上の方法はありません。

途中で質問が生じた場合は、SwaggerHub Integrations のページをご覧ください。このページでは、Git などのソース コントロール管理ツール、ビルド ツール、API 管理プラットフォーム、Webhook など、SwaggerHub がサポートするさまざまな種類の統合機能が紹介されています。

オフィスにはまだ入ることができませんが、API デザインに関する多くの情報や、あなたをシャープにするためのインタラクティブなビデオやトレーニングを受けることができます。なお、SmartBear Connect 2020 では、この他にも数多くのビデオをオンデマンドで視聴することができます。

SwaggerHub 製品紹介ページは、こちら
OpenAPI 仕様に準拠した API 設計とドキュメント化のためのプラットフォーム

この資料は、SmartBear の Blog で公開されている「SmartBear Connect 2020 Recap: Using SwaggerHub Registry API to Streamline CI/CD Integration」の日本語参考訳です。

シェアする

  • このエントリーをはてなブックマークに追加

フォローする