文書化する API エンドポイントがたくさんあり、POST および PUT 要求のペイロードは複雑になる可能性があります。私はapiblueprintでそれらを文書化しています。apiblueprint を使用して URI パラメーターを文書化できる方法がとても気に入っています。見栄えがよく、読者が必要とするすべての情報（必須、文字列または整数、選択肢/値のリスト、例の提供）を提供できます。
Request セクションを見ると、同じレベルの元のドキュメントを提供する方法がわかりません。私が見たリクエスト セクションは、リクエストの例を示しているだけです。
必要な id という名前の整数を取る単純なペイロードを扱っているとします。現在、私のリクエストセクションは次のようになります。
ヘッダー
コンテンツ タイプ: アプリケーション/json
体
{"id":"123"}
リクエストの本文はこれほどスパースである必要がありますか? REST ペイロードのすべての制約/要件をユーザーに伝える最善の方法は何ですか?