APIドキュメントの完成度、どんな基準でスコアを付ける?
良いAPIドキュメントは、開発者が問い合わせなしですぐに連携できるようにします。このツールは開発者がAPIドキュメントで最も頻繁に確認する8つの要素をチェックリスト化し、ドキュメントの完成度を100点満点でスコア化します。
最も配点が高い項目は、エンドポイント説明、リクエスト/レスポンス例、パラメータ仕様、エラーコード説明で、それぞれ15点が割り当てられています。この4つは開発者が実際にAPIを呼び出す前に必ず確認する情報だからです。認証方法、Rate Limitポリシー、Changelog、Try it out機能はそれぞれ10点と相対的に低く設定していますが、本番連携の段階では依然として重要な要素です。
スコアが60点未満の場合、開発者が問い合わせを頻繁に残したり、誤った方法でAPIを呼び出す可能性が高くなります。配点の高い項目から順に補完することで、最も効率的にドキュメント品質を上げられます。
よくある質問
このチェックリストはすべてのAPIドキュメントに適用できる?
REST、GraphQLなど大半のAPIドキュメント形式に共通して適用できる項目で構成しています。ただし内部用APIは一部項目を緩和して適用しても構いません。
Try it out機能がないとスコアが大きく下がる?
10点しか減点されないため、他の7項目をすべて満たせば90点を獲得できます。実際の呼び出しテスト機能は相対的に優先度が低い項目です。
スコアが低い場合、どの項目から改善すべき?
配点の高いリクエスト/レスポンス例、パラメータ仕様、エラーコード説明を先に埋めることが、ドキュメントの使いやすさ向上に最も効果的です。