API仕様書を作っていて、基本的な点についてのまとめ
- コードと連動できれば理想(現実的には設定ファイルをJSONかYamlで作るぐらいが限界だと思う)
- 型のチェック、必須チェック、桁数チェック、日付の場合のフォーマット指定→バリデーション設定ファイルと連動できれば理想
- 桁数は更新系の場合、DBの桁数とあっているかの確認。
- リスト系の値などはマクロで自動出力できるのが理想。
- コード値で出すのか表示文字まで出すのか
- 数値でいくのか、文字でいくのか(見た目数値なのに型が文字などのようなものは混乱につながるので数値で統一したほうが良いと思う。)
- リクエストのサンプルをExcelから自動で出せるようにしておく、あるいはコードから出せる形にしておく
- レスポンスはできればExcelから自動で出せるようにしておく、あるいはコードから出る形にしておく
- 意味のあるダミーのリクエスト、レスポンスが生成できると関係者が幸せになる
- HTTPコードとエラーメッセージ(これもExcelから自動で出れば一番)
- マクロやPythonを利用して、入力する部分をなるべく減らす
- 改訂履歴は必ず残す(verを指定できるのが一番良い)
