skillup

技術ブログ

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

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

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

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

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

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

執筆者:


comment

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

関連記事

no image

Eclipseでのソースフォーマットでの自動改行を防ぐ

小ネタ。Eclipseのソースフォーマッタはディフォルトでは一定の字数で改行されしまい、大変見にくくなったりします。 またHTMLなどでは改行してほしいタグが改行されないなど思ったとおりに動いてくれま …

no image

マイクロサービスについて

マイクロサービスについて勉強したので少しメモを。 参考文献 Software Design 「2020年1月」 Contents1 マイクロサービスとは?1.1 具体例1.1.1 フロントエンドとバッ …

no image

ミスを少なくする工夫について

プログラマであればだれもが「いかにバグを少なくするか」に腐心すると思います。 ところが、人間がある以上、バグ(ミス)は絶対にゼロにはなりません。バグ云々以前に、「人間はもともとミスをする生き物だ」とい …

no image

外結〜運用フェーズでの気をつけることなど

外結以降のフェーズで注意することなど。(主に障害発生時の原因切り分け) Contents1 エラーの情報伝達に関して2 ログの見方3 デプロイ4 タスクコミュニケーション(タスク管理ツール)5 チャッ …

no image

調査スキルについて

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

アーカイブ