skillup

技術ブログ

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

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

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

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

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

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

執筆者:


comment

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

関連記事

no image

設定ファイルの置き場所

一般的にレベルの高いソースとは保守性が高いものを指します。特にWEB系ですと仕様変更がしょっちゅうなので変更があったときにいかに少ない工数で対応できるかが大切です。 保守性をあげる工夫はいろいろありま …

no image

調査スキルについて

本日は実務でとても大切な不具合の発見方法について 通常のプログラマとして仕事をしておりますと、通常の実装よりは不具合時の調査のほうが難しいことが多々あります。 もちろんものによるんですが、経験のある人 …

no image

コードの抽象化

リーダブルコードも終盤に少しずつ近づいてきました。 今まではどちらかというとコードの点や線の技術に注目してきましたが、これからは面的な要素に注目していきます。 リーダブルコードでは「無関係の下位問題を …

no image

Webの高速化に関して

Webの高速化に関してメモ。 高速化って言っても幅広いんですけどね。自分が行なっている対策に関して。 一応LAMP環境を前提にしてます。 Contents1 一番大事なのは測定2 DB対策3 フロント …

no image

ログインしたままにするの挙動に関して(ステートフル認証の基本的な仕組みの復習もかねて)

基礎の基礎ですが、ログイン処理に関しての動きに関して。 Contents1 通常のログイン処理に関して2 ログインしたままにする 通常のログイン処理に関して 通常のログイン処理では、まず以下のような手 …

アーカイブ