skillup

技術ブログ

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

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

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

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

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

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

執筆者:


comment

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

関連記事

no image

DIが役に立つ場面はやはりテスト

システム開発において、密結合とか疎結合なんて言葉が使われたりします。 密結合・・システム間の構成要素の関連性が高く、結びつきが密なこと 疎結合・・システム間の構成要素の関連性が弱く、結びつきが疎なこと …

no image

コード静的解析ツールを使った際の気づきなど

最近のプロジェクトでコード静的解析ツール(phpcs,phpmd)を使った際の気づきなど コードを書きながら常時エディタがチェックするタイプのものでないとまず無理(保存するたびでも無理だし、コミット時 …

no image

VSCodeのPluginなど

Vscodeで使っているPluginなど Contents1 基本2 UML3 git4 PHP コードフォーマット5 golang6 CSV整形 基本 Japanese Language Pack …

no image

プロジェクトごとのフェーズでやっておいたほうが良いと思うこと

またプロジェクトの途中ではありますが、自分の中で要件定義〜外部結合の始まりまでのフェーズを経験して思ったことなど Contents1 全般2 要件定義3 基本設計4 詳細設計5 製造6 単体テスト〜内 …

no image

短いコードを書く

私が普段コードを書くときに考えていることは常にいかに短くかけるか、ということといかにバグを生み出さないかということです。 基本的にはできるだけ、短くシンプルに書くようにしています。 そうすることであと …

アーカイブ