skillup

技術ブログ

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

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

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

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

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

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

執筆者:


comment

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

関連記事

no image

ファジープロジェクト対策 その1

5月ぐらいから着手していたプロジェクト(顧客管理ソフト)が終焉を迎え、検証段階に入ったので、記して置きたいことなど。 数ヶ月程度ですが、自分が携わったプロジェクトの中では過去最大クラスのものでした。 …

no image

ファジープロジェクト対策 その2

前回に引き続き、大事だと思ったこと。一部単なるフレームワークの作り方的な内容になっているかも。 Contents1 テンプレート共通化2 バリデーション3 ログ出し4 異常系の処理5 新規プラグイン+ …

no image

データ構造の基礎知識 中編 ハッシュ

前回の続きです。 前回は配列、連結リストについて学習したので今回はハッシュについて学習します。 Contents1 ハッシュとは?1.1 メリット1.2 デメリット ハッシュとは? key-value …

no image

ドメイン決定&業務フローとの対応確認

Contents1 ドメイン決定2 業務フローとの対応2.1 実際の業務とエンティティ、画面の遷移2.2 ドメインのCRUD分析 ドメイン決定 業務フローを抽出し、エンティティを抽出した段階で次にドメ …

no image

フレームワーク作成時の注意ポイント

以前も多分書いていますが、フレームワーク作成時のポイントなどを列挙。 次元が違うものも多々含まれているかも。 ルーティング機能 基本設定情報の読み込み キャッシュ機能 データベース Form情報の管理 …

アーカイブ