API開発がここ数年で飛躍的に進んでいることは周知の事実です。当社の2019年API業界レポートでは、組織の3分の2が過去5年以内にAPI開発を開始したことがわかりました。組織がAPIプラクティスを拡大するにつれて、以前はSwaggerと呼ばれていたOpenAPI仕様に沿ってAPIを設計するためのツールを採用し始めています。
SwaggerHubは、チームがREST APIを整理および管理し、同時にデザインプラクティスを拡大および標準化できるコラボレーションプラットフォームです。
プラットフォームを使い始めたチームから、よく次のような質問を受けます。
「API設計とドキュメントにSwaggerHubを最大限に活用するために、チームが採用すべきベストプラクティスは何ですか？」
以下に、クラス最高のAPI設計につながるSwaggerHubの5つのベストプラクティスをご紹介します。
1. 組織全体でAPI標準化を定義し、実施する
2019年APIレポートでは、APIを開発および利用するチームにとって最大の課題は「標準化の欠如」でした。チームが構築し、依存しているAPIが一貫した方法で設計されていない場合、それらのAPIとのインタラクションやメンテナンスが難しくなります。
SwaggerHubでは、スタイルガイド準拠のチェックを簡単に自動化できます。組織に適用するスタイルルールを選択するだけで、どのAPIを更新する必要があるかをすぐに確認できます。
チームが新しいAPIを設計すると、これらのスタイルルールがエディターに表示され、すべての新しいAPIが標準化された一貫した方法で構築されるようになります。
現在、チームがデザインの一貫性を確保するために手動レビューを行っている場合、このスタイルチェックの自動化により、かなりの時間を節約し、エラーを減らすことができます。スタイルエラーを指摘する代わりに、これらのレビューは知識の共有とベストプラクティスに焦点を当てることができます。
2. 組織、プロジェクト、チームでAPI定義と権限を管理する
会社によっては、何百もの異なるAPIに取り組んだり、連携したりしているかもしれません。組織がGitHubやBitbucketのようなリポジトリにのみ依存している場合、誰が何を所有しているかを明確に把握するのは困難です。SwaggerHubでAPIを管理することで、すべてのAPIとドキュメントの信頼できる集中ソースを確立できます。
SwaggerHubの組織は、グループが所有するAPI定義と、それらにアクセスできる人の権限を管理するシンプルな方法を提供します。同僚をメンバーとして招待し、既存のAPIをインポートすることから始めます。次に、メンバーをチームに、APIをプロジェクトにグループ化し、SwaggerHub Editorで新しいAPIの設計を開始します。
社内では、SmartBearは全社的な開発組織を持ち、各ツールごとにチームとプロジェクトを組織しています。たとえば、SmartBearのUIパフォーマンステストプラットフォームであるLoadNinjaのエンジニアリングチームは、内部および外部のAPIドキュメントをホストするためにSwaggerHubを使用しています。SwaggerHubは、開発者がLoadNinjaのさまざまな内部サービスで共同作業し、理解するための中央の信頼できるソースとして機能します。
3. 共通APIコンポーネントのドメインを作成する
当社の2019年APIレポートでは、回答者の75%が、今後2年間でマイクロサービスアーキテクチャがAPI採用の最大の成長を牽引すると考えていると述べています。これは2016年には20%しかありませんでした。チームがAPI開発を拡大している場合、パラメーター、レスポンス、データモデルなど、作業全体で共通のコンポーネントがある可能性があります。
すべてのAPIに404エラーを記述する代わりに、SwaggerHubのドメインを使用すると、これらの共通コンポーネントのライブラリを構築することで、Don't Repeat Yourself（DRY）原則に従うことができます。Errorsドメインで404エラーのスキーマを参照し、設計を続行するだけです。
この再利用性により、チームの手作業が減り、プロジェクト全体のリスクが低減されます。また、変更が行われ、標準化された要素が進化しても、更新が必要な場所は1つだけになります。
前述のとおり、設計の標準化は2019年のチームにとって最大の課題です。ドメインを使用すると、組織は標準的な定義を使用できます。「顧客」または「従業員」の定義がビジネス全体で一貫している場合、エンドユーザーはAPIと対話するときに何を期待すべきかをはるかに簡単に知ることができます。
4. 自動モックによる早期設計検証
チームが設計を早期にテストすればするほど、それらを反復し、問題を修正するのが容易になります。デザイナーがSwaggerHub Editorを使用してSwagger定義を作成および視覚化すると、SmartBearの別のツールであるVirtServerとの統合により、組み込みの自動モックを使用して早期に動作を検証し始めます。
このVirtServer統合は、SwaggerHubで定義されたAPIの半静的モックを自動的に作成および維持します。このモックはAPIを保存するたびに更新されるため、モックサービスを作成するためにわざわざする必要がなくなります。VirtServerによって生成されたプレビューを使用して、チームと設計を反復することができます。これらすべてが数回のクリックで可能です。
自動モックはデザイナーに作業に関する即時フィードバックを提供しますが、ソフトウェアチームの他のメンバーの作業方法にも影響を与えます。モックが配置されると、開発者はバックエンドAPIの作業が完了するのを待つことなく、クライアントアプリケーションを並行して開発し始めます。
5. SwaggerHubをCI/CDパイプライン戦略に組み込む
多くのチームは現在、ソフトウェア開発ライフサイクル全体の異なるツールを統合することでCI/CDパイプラインを構築しようとしています。
SwaggerHubは、AWS、Microsoft Azure、IBM API Connect、ApigeeなどのAPI管理プラットフォームとネイティブ統合されているため、デリバリーパイプラインに簡単に組み込むことができます。
SwaggerHubは、組織のREST APIの信頼できる情報源である場合に最も役立ちます。API定義をGitHub、Bitbucket、GitLabなどのソースコードリポジトリと同期することで、プラットフォーム全体および組織全体のドキュメントとコードの両方でバージョン管理の一貫性を確保できます。チームは、SDKやコードテンプレートをこれらのリポジトリシステムにプッシュすることもでき、新しいサービスの構築に必要な多くの作業を削減し、開発者がロジックと機能にまず集中できるようにします。
SwaggerHub Webhookを設定してカスタムワークフローを作成することもできます。たとえば、SmartBearのWebテストプラットフォームであるCrossBrowserTesting.comのチームは、SwaggerHubを使用してAPIを定義し、ドキュメントを一元的に管理しています。Webhookを使用すると、SwaggerHubをJSON定義ファイルをリアルタイムで取得し、統一された方法で表示するテンプレートツールと接続しています。
はじめに
すでにSwaggerHubを使用しているチームで、これらのベストプラクティスについて質問がある場合は、遠慮なくお問い合わせください。まだSwaggerHubを使用していない場合は、無料アカウントを作成し、既存のAPIをインポートすることから始めることができます。