skillup

技術ブログ

ドキュメント作成 プログラミング全般

API仕様書に関する注意事項

投稿日:2021年10月13日 更新日:

API仕様書を作っていて、基本的な点についてのまとめ

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

-ドキュメント作成, プログラミング全般
-

執筆者:


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

no image

フレームワークのマイナーバージョンチェンジの影響に関して

ここ1年ぐらいPHPのフレームワークはLaravelを使っていますが、マイナーバージョンの影響に悩まされることがたまにあります。 以前、遭遇した事象としてはログイン連携が急にできなくなりました。 La …

no image

画面テストのツールに関して

Unitテストに関してはxUnit一択だと思いますが、UI系のテストツールについて。 IDE(コードを書かずにすむマクロ系)に関して全てChromeで動くことを確認しています。 Contents1 ツ …

no image

正規表現に関して

SQLネタをいろいろと書いておりますが、ちょっとワンポイント的なネタで正規表現について書きたいと思います。 平均的なものは知っているつもりでしたが、シェルの正規表現について知らなかったのでちょっとメモ …

no image

オブジェクト指向設計 柔軟なインターフェイス

オブジェクト指向シリーズ。今回はインターフェイスについて。 インターフェイスといっても、implementsを使った実装だけではなく、要はあるクラスが外部の窓口となるときに使うメソッドってことだと思う …

no image

トランザクション、ロールバックに関する考察

今までトランザクションの単位は基本的に処理の開始から終了までを範囲にすることが多かったのですが(ループがある場合はループ全体ではなく、1ループをトランザクションとみなします)、複数の処理が絡む場合、不 …