開発組織が成熟し、API デザインファーストのプロセスに移行していく中で、API が本来の動作をするだけでなく、長期的な使用と採用を前提に設計されていることを確実にしたいと思います。 このような理由から、ブランディング スタイル ガイドに似た API スタイル ガイドを作成し、組織全体でどのように API を設計すべきかを規定することが考えられます。
API スタイル ガイドは、すべての API における一貫性を確保し、DX (デジタル トランスフォーメーション) の加速、エンジニアのオンボーディング(教育、研修)の容易化、API が業界のガイドラインに従っていることの確認、そして社内外の API 利用者にポジティブな開発者体験を提供するなど、複数のメリットをもたらします。
SwaggerHub はどのように役立つのか？
SwaggerHub は、組織のスタイル ガイドに従うことを支援するという点で、API デザイナーの味方です。 操作やパラメータ、モデル定義が準拠しているかどうかをチェックするルールが組み込まれています。 また、SwaggerHub を使用して独自の社内 API 標準化ガイドを構築することもでき、ルールのリストから選択したり、独自のルールを追加したりすることができます。 ルールを設定して API を設計すると、SwaggerHub は不整合を検出してエディタで即座にフィードバックします。 そのため、実際に実装を開発して API をレビューする前に、設計の早い段階で問題を修正することができます。
簡素化、簡素化
SwaggerHub を使ってルールを設定し、それを API 設計のプロセスで実施するのは簡単です。 まず、組織のオーナーは、SwaggerHub の組織設定セクションで「標準化」を有効にします。 その際、あらかじめ用意されているルールを選択するか、カスタムルールを作成します。
ルールを有効にすると、SwaggerHub は組織内のすべての API をスキャンして、スタイル ガイドに準拠していない API にフラグを立てます。 API をフィルタリングして、標準化ルールに従っていないものだけを表示することもできます。 エディタ内では、SwaggerHub が API 定義ファイルのエラーをハイライトしてくれるので、簡単に修正することができます。
API の標準化についてさらに詳しく知りたい方は、SwaggerHub で REST API を標準化するビデオをご覧ください。
SwaggerHub を使用してカスタム ルールを作成
業界固有の API ルールやスタイルガイドは独自のものであるため、実質的にはコンプライアンスを強化するためのガバナンスのガードレールとなります。 SwaggerHub では、組織が業界固有のスタイルガイドを用いて API 標準化のための独自のカスタム ルールを書くことができます。また、OpenAPI の定義が API 設計ガイドラインに準拠しているかどうかを検証することができます。
例えば、スタイルガイドが API に MAJOR.MINOR.PATCH バージョンを要求している場合、標準化スタイルガイドに簡単に追加することができます。 [Create Rule (ルールの作成)] ダイアログで、ルール名、パス、正規表現パターンを追加します。 そのルールに違反した場合に API を公開したくない場合は、重大度を “Error” に設定します。 または、API 設計者がデバッグしやすいように、カスタム エラーメッセージを追加します。 ルールを設計する際には、YAML エディタを使用して、ルールが正確にキャプチャしたいものをキャプチャすることを確認できます。
これを実際に見てみましょう。
ルールの例をご紹介します。
| ルール | パス | 正規表現 |
| バージョンは、major.minor.patch でなければなりません。 | $.info.version |
^([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+)?$ |
| OpenAPI 3 でなければなりません | $.openapi |
/^3\.\d+\.\d+$/ |
| すべての操作に200の応答が必要です | $.paths.*[put,post,get,delete,patch,options].responses.200 |
存在しなければなりません |
| すべての操作に400の応答が必要です | $.paths.*[put,post,get,delete,patch,options].responses.400 |
存在しなければなりません |
| すべてのオブジェクト名にはキャメルケースを使用する必要があります | $..properties.*~ |
^[a-z]+[A-Za-z0-9]*[a-z0-9]+$ |
| すべての属性名には、キャメルケースを使用する必要があります | $.definitions.*~ |
^[a-z]+[A-Za-z0-9]*[a-z0-9]+$ |
| エンドポイントのURLは小文字でなければなりません | $.paths.*~ |
^[\/a-z\{\}]+$ |
カスタムルールは、組織がこの機能を活用する新たな方法を模索し、独自の業界標準で API ガバナンスを実施することで、今後も増え続けるでしょう。
次のステップ
SwaggerHub エディタにスタイル ガイドの施行を追加することは、始まりに過ぎません。 年内には、ルール施行のための API と CLI のサポート、ビルドパイプラインに直接ルールを追加できるようにすること、他の API 設計者とルールを構築・共有するためのルールライブラリなど、この機能の強化を予定しています。
SwaggerHub : OpenAPI 仕様に準拠した API 設計とドキュメント化のためのプラットフォーム
この資料は、SmartBear の Blog で公開されている「API Rules – Guardrails for Good Governance and Best Practices」の日本語参考訳です。
