Web開発でREST-APIが採用されるケースは未だ多いと思います
ですがREST-APIは思想のようなもので、大した仕様が定義されていません
「REST-APIでやろう」というのはHTTPSでいい感じにやろうやと言っているのと同じくらいルールがない状態です
なんの取り決めもなく進めるとカオスになります
REST-API採用時、最低限のガイドラインとなる仕様やツールを紹介します
[仕様] OpenAPI (Swagger) を使う
OpenAPIはREST-APIを記述するための仕様の1つです。これに従って記述することで秩序が生まれます
例えば、以下のようなIDをkeyにしたDictionary形式のレスポンスはOpenAPIで表現できないのでNGです
{
"users" : [
"1": {"name": "hoge"},
"2": {"name": "fuga"}
]
}
REST-APIの簡素な思想と違って、OpenAPIは割と仕様がマッチョです
全部読むのは大変なので、困ったときに見る形でOKだと思います
Version 3以上を使う
Version 3以上を使いましょう。ファイルの先頭に書きます openapi: "3.0.x"
新しいバージョンを使うの理由は、単純にドキュメントの探しやすさです
古いSwaggerのサンプルでは version: 2を使っているケースがあるので注意しましょう
[Viewer] Swagger UI で見る
これはチームで統一されていれば何でもいいと思います
Swaggerが導入しやすいと思うので紹介します
Swagger Editor (Online)
デモの入力欄にコピペすればpreview欄（右側)に反映されます
コピペする手間はありますが、何の準備もいらないので楽です
VSCode プラグイン
VSCodeで開発をしているならこちら
いくつか種類があるようなのでお好きなものを
Docker
Swagger UIの Docker Imageが公開されているので、オンラインデモと同じ環境を自分で構築することができます
自分が試したときはこちらの記事を参考にさせてもらいました
docker-composeでSwagger【Swagger】【Docker】
[Editor] Stoplight Studio で書く
OpenAPI記述をめちゃ楽にしてくれる最高のアプリです
YAML手書きのペイン集 
YAMLを手書きするにはOpenAPIの知識がそこそこ必要
チームで記述しているとわずかに個人差が出るので統一感がなくなっていく
OpenAPI的に不正な構文でもSwaggerUIがよしなに表示してくれたりするので、間違いに気づけなかったりする
Stoplight StudioならUIに従って書いていくだけなのでほとんど迷いがないです。個人差も出ません