結論
使う人のことを考えてAPI仕様書作成しましょう。あなたが使う側になった時そのAPI仕様書で理解できますか？
困ったAPI仕様書達
API仕様書読んで困ったことを思いついたら挙げていきます。ポエムだと思って読んでいただければ
PUT(POST)APIのpayload 例が空のjsonだった時
APIのrequest sample 書いてくれるのありがたいです。助かります。ただPUT APIで空のjsonがsampleに書かれていた時は絶望しました。何を設定しろと？
パラメータにもpayload : set update valuesとしか書いていないので頭が痛くなりましたｗ
↓絶望したサンプル。何を伝えたかったのだろうか……。
{}
response で返却される項目が必須なのか任意なのかわからない
これは要望なんですが、responseで返却される項目がAPIで必ず設定して返してくれるのか、それとも項目自体が返ってこないのか明記して欲しいです。
同じシステムのAPIなのに、APIによって、項目がキャメルケースだったりスネークケースだったりする。
実際にあった話。AというAPIではキャメルケースなのに、BというAPIではスネークケースで項目が書かれていて？？？となりました。
同じシステム内のAPIでは統一して欲しいものです。
どこまでがojcectか分からない・・・
エクセルAPI仕様書であった話。返却される項目の型にobjectと書かれていたのですが、どこまでがobjectか分からない・・・object内の項目はインデント付けて分かるようにして欲しかった（文・・・改善要望あげて改善してもらいましたが）
項目の説明がまともに書かれていないAPI仕様書
Open APIで書かれているものでよく見かけるやつ。
id : integerのように型の説明しかないやつ。idくらいならまだしもすべての項目の説明が型だけだった時は、ソウルジェムが濁るどころの話じゃないし、
書いた人に小一時間問い詰めたくなるやつ。読み手にちゃんと情報を与えるようにドキュメントを書いてくれまじで。