SYSTEM-5-4

クライテリア

APIは何らかのSchema定義言語によって規定され、そこから自動的にクライアントの生成やバリデータの生成が行われているか。

タイプ

API駆動開発

観点

プラクティス

用語解説

Schema定義言語

OpenAPIやProtocol Buffersといった手法を使うことによって、API仕様をドキュメントに起こしたり仕様をコーディングやモック環境に反映させる手間を省くことができます。

参考資料

API 記述言語や API ドキュメンテーションツールの比較(Swagger、API Blueprint、RAML) - Qiita

「最近」というには最近すぎる気がしますが、今日のシステム開発では、変化し続ける要件に対応するため、システム自体にも柔軟性がもとめられています。 その中でも、サーバーとクライアント、またはサーバー同士のやり取りのためのインターフェイスである Web API(以下、小面倒なので平たく API と呼びます)は Web システムにとって、もはや欠かせないものだと思います。 その API を設計する際には多くの人が RESTful API を採用するでしょう。 しかし、採用したものの設計方針が人によって微妙にバラつきがあったり、ドキュメントの運用保守ができていなかったり、モックや API コンソールを作らなければならなかったり、ドキュメントからではなくコードから書く人がいたりと、開発規模や状況に応じていろいろなレベルの課題が存在します。 そろそろ上記のようなことは API 設計が終わった段階で 8 割くらい終わっている状態にしたいですよね。 API の保守は、ソースコードそのものだけでなく、ドキュメント、API コンソールやスタブ、単体テストなど影響が広範囲に及びます。 それらの解決の手助けをしてくれるのが API ドキュメンテーションツール(一部では API フレームワークとも呼ばれている?)です。 API ドキュメンテーションツールは、設計から開発、ドキュメント生成までをワンストップでサポートします。 最近のツールでいうと、そのツールが対応している記述方式(API 記述言語というべきか?)で API を定義することで、以下のようなことができます。 機能名 説明 ドキュメント 記述方式に則って書いたものがユーザーに見易い形でドキュメント生成されるような機能です。 エディター 記述した定義がフォーマット通りか検証してくれたり、書いたものがすぐにドキュメントプレビューされるような機能です。 コンソール API のリクエストパラメーターを書き換えて API を実行するための機能です。リクエストをモックサーバーか実際の API サーバーに向けることで、リクエストに応じた結果が返ってくるでしょう。 モック

API 記述言語や API ドキュメンテーションツールの比較(Swagger、API Blueprint、RAML) - Qiita