SYSTEM-5-4

2021/1/20 15:552021/3/24 16:46

クライテリア

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 サーバーに向けることで、リクエストに応じた結果が返ってくるでしょう。モック

https://qiita.com/tetsukamp/items/a05f40fcab6d528b1e4f