SwaggerHubチームは最近、DockerCon 2017に参加するため、テキサス州オースティンへ出張しました。 DockerConは、5,000人以上の開発者、DevOps担当者、システム管理者、その他Dockerコミュニティの人々が集まる、世界最大のコンテナ技術カンファレンスです。
なぜ今年、DockerConに参加したのでしょうか？
この1年間で、マイクロサービスアーキテクチャに投資するソフトウェアチームの間で、SwaggerHubプラットフォームの採用が著しく増加しているのを目の当たりにしました。 3日間で、マイクロサービスやAPIの導入過程にある様々な段階の人々と何百もの会話をする機会がありました。マイクロサービスアーキテクチャの実装を支援するためにSwaggerツールとOpenAPI仕様を使用している多くの人々から話を聞き、APIチームのニーズに対応するためにSwaggerHubをどのように進化させ続けることができるかについてさらに学ぶことができて大変うれしく思いました。 今年のイベントのフォローアップとして、DockerCon 2017での会話から学んだ重要な洞察をいくつか共有したいと思います。
1. OpenAPI (Swagger) 仕様は、マイクロサービスへの移行において重要な役割を果たす
モノリシックアプリケーションからマイクロサービスアーキテクチャへ移行する組織は、通常、互いに通信するためのサービスを公開するためにAPIに依存します。APIを介してサービスをより適切に公開するには、各サービスが何を行うべきかを正確に伝えるための共通のインターフェースが必要です。 OpenAPI (Swagger) 仕様 (OAS)は、この契約を定義するための標準フォーマットとして登場し、クライアントとサービス間のSLAを、人間にも機械にも読みやすい方法で定義する共通インターフェースを提供します。DockerConで一週間を通して話を聞いたチームにとって、OASでAPIを定義する主なユースケースは、内部チームがAPIを扱うために必要なドキュメンテーションを生成することであり、Swagger UIがこの仕様の最も人気のある実装となっています。
2. ほとんどのチームは依然としてAPI開発において「コードファースト」アプローチを採用している
API開発、あるいはマイクロサービス構築におけるデザインファーストアプローチの利点については、多くのことが書かれています。デザインファーストアプローチでは、最初にマイクロサービスのインターフェースを設計・定義し、この契約をレビューして安定させ、その後サービスを実装します。しかし、デザインファーストが理想的であるにもかかわらず、私たちが話を聞いたほとんどのチームは依然としてコードファーストアプローチに従っており、オープンソースツールを組み合わせて、既存のAPIから（実行時またはビルド時に）Swaggerファイルを生成しています。 私たちが話を聞いたほとんどの人にとって、Swaggerに「コードファースト」アプローチを採用する決定は、デザインファーストアプローチに移行するよりもはるかに迅速に実装できるというものでした。コードファーストアプローチでは自動化がはるかに容易であるという事実がこのケースを強化しており、多くのライブラリがサーバーコードのスキャフォールディング、機能テスト、デプロイ自動化をサポートしています。 詳細はこちら：[無料ダウンロード] 既存のAPIにSwaggerを追加する方法
3. スタイルの一貫性はAPIチームにとって増大する課題である
チームがソフトウェアシステムを実装するためにどのようなアーキテクチャを使用しているかに関わらず、チームが優れたAPI開発者エクスペリエンスを真剣に考えているのであれば、チームが従うべきいくつかのガイドラインがあるでしょう。しかし、私たちが個人にこれらのガイドラインをどのように実施しているかについて尋ねたところ、改善の余地があることは明らかでした。 私たちの議論から聞いた4つの共通の傾向は次のとおりです。
- 作成中のすべてのSwaggerファイルを追跡する
- 既存のAPIのバージョン管理を処理する
- 開発者チーム全体でスタイルガイドラインを強制する
- 複数のサービス間で共通のデザインオブジェクトを再利用しやすくする
SwaggerHubは、APIデザインの一貫性と再利用性をドメインとStyle Validatorを使用して促進しながら、チーム全体がSwaggerを使用してAPIのライフサイクル全体で作業できる中心的な場所を提供することで、これらの課題に対処するために構築されました。 Style Validatorは、RESTfulインターフェースが組織の要件に基づいて標準の設計図に準拠していることを保証します。これは、すべてのインターフェースがキャメルケース演算子、レスポンスパケットに定義された例、またはモデルがローカルで定義されていることを保証することを意味します。ドメインでは、モデルやリクエスト/レスポンスオブジェクトなど、共通の再利用可能な構文を保存でき、マイクロサービスビジネス機能を提供する複数のAPI間で迅速に参照できます。
4. API管理ソリューションはマイクロサービスアーキテクチャにおいて重要な役割を果たすが、デザインは非常に必要とされているソリューションである
API管理ソリューションは、マイクロサービスのオーケストレーションにおいて重要な役割を果たします。セキュリティ、モニタリング、アナリティクス、ディスカバリのメカニズムを備えたこれらのプラットフォームは、マイクロサービスアーキテクチャの一部として多数のAPIを処理するのに役立ちます。 しかし、多くのAPI管理ソリューションがデザイン機能を提供している一方で、APIデザイン専用のツールセットの必要性も明らかになっています。優れたAPIデザインは、公開または非公開のAPIにとって重要です。私たちのブースでの議論中にSwaggerユーザーの一人が言ったように、「外部の開発者に対して提供するのと同じ質の体験を、APIを開発する内部チームにも提供する必要があります。」 スタイルガイドラインを設定したら、APIのデザインに一流の対応を提供するツールが必要です。Swaggerを始めたばかりのチームにとっては、Swagger Editorのようなオープンソースツールが、定義を記述および更新するために必要なツールを提供できます。デザインをAPI管理プラットフォームとシームレスに統合する必要がある高度なチームにとっては、SwaggerHubのような完全に統合されたプラットフォームが役立ちます。
5. APIチームはAPIドキュメントをホストおよび管理するより良い方法を必要としている
APIを使用してサービスを一般公開する場合でも、独自のソフトウェアアーキテクチャ内で公開する場合でも、最新でアクセスしやすいドキュメントを持つことが重要です。これが、そもそもチームがSwaggerの実装を開始する最大の理由です。しかし、APIドキュメントが1つのチーム内で数バージョンから、数十、数百の異なるAPIに及ぶようになると、これらのドキュメントの維持が問題となる可能性があります。 Swaggerユーザーからよく聞かれる一般的な解決策の1つは、GitHubやBitbucketなどのソース管理ホストにドキュメントをホストすることです。しかし、これらのツールはソースコードのホスティングには優れていますが、利用可能なすべての異なるドキュメントに1つの中心的な場所から簡単にアクセスできるようにするわけではありません。結果として、ほとんどのチームは代わりに内部ソリューションを見つけることになります。 私たちはSwaggerHubで代替ソリューションを提供するために取り組んできました。これにより、APIのすべてのドキュメントを1つの中央集中型ホストプラットフォームからホストおよび維持できます。SwaggerHubは、プライバシーの管理、バージョンの公開および非公開、さらにはEnterpriseプランで独自のサーバーでのホスティング機能を提供することで、組織の内部APIカタログとして機能できます。 詳細はこちらをご覧ください。 今年のDockerConイベントでSwaggerHubブースにお立ち寄りいただいた皆様、誠にありがとうございました！SwaggerHubにご興味をお持ちの方は、こちらから無料でご登録いただけます。ご質問がございましたら、チームまでお問い合わせください：[email protected]