APIドキュメントの書き方をまとめてみる - あらにわ背景 転職してサーバサイドエンジニアとして、RESTfulなWebAPIドキュメント書く機会が増えた。 RESTの歴史はそれなりに長いため、仕様書の書き方にもベストプラクティスが確立されている。 なので、今更感もあるが、せっかくなのでまとめてみようと思う。 心構え 出来の良いAPI仕様書をマネすること ユーザの対象を意識すること（社内利用か社外利用など。仕様書で意識するポイントが変わるため） トリッキーな使い方をするエンドポイントは疑う 最低限記載すること 共通項目 ドキュメントのメタ情報（バージョン、更新日付など） 常に必要なパラメータ（認証系） 流入制限 エンドポイント（URI） HTTPメソッド（GET、POST、PUT、DELETE、HEAD、OPTIONS、TRACE、CONNECT） Description（概要） Notes（備考） リクエストについて パラメータ（クエリパラ
