Web API設計時に使われ方の想定を添えると良い。けどより良いやり方を知りたい

先日登壇したイベントにて、仕事で協業したモバイルエンジニアから「Web APIのドキュメントに使われ方の想定が添えられていてありがたかった」とフィードバックをもらった。 具体的にはX post (以下、tweet) に添付した画像のような感じで、Web API (以下、API) が呼び出される画面・タイミングの想定、レスポンスの使われ…