Spring RESTでドキュメントの応答ステータス

Question

私は現在、RESTfulなサービスのドキュメントを生成するためにSpring REST Docsを使用していますが、完了したような応答ステータスの可能な値のテーブルを生成したいのですが、hereページの）。

親のindex.adocファイルを手動で作成することはできますが、生成されたものも含まれていますが、私はドキュメントを一掃してしまいます。

私はREST Docsのドキュメントを読んで、StackOverflowとそのプロジェクトのGitHubの問題を検索しましたが、このような機能は何も言及していません。

私は何かを見つけられませんか、または私が探している機能が実装されておらず、必要でもありませんか？

Answer 1

あなたが探している機能は実装されていません。私の意見では、この機能は必要ありません。

RESTful APIを開発してドキュメント化する場合は、HTTPステータスコードの使用方法を可能な限り一貫したものにするようにしてください。また、各ステータスの標準的で分かりやすい意味も使用する必要があります。この2つのガイドラインに従っている場合は、ステータスコードを完全に文書化しないでください。または概要セクションで一度文書化することもできます。

あなたは私はあなたが何をすべきとは思わないもののいくつかの例を提供するためにリンクしたドキュメント：

1. それは200のリクエストが成功したことを意味していることについて説明します。これは200応答の標準的な意味であり、文書にはほとんど追加されていません。
2. 402はブロックされたAPIキーに使用されますが、実際には支払いが必要です。 403（禁止）応答は、HTTPステータスコードの非標準的な使用を意図した製造、
3. それ侵害404（見つかりません）がレート制限は要するに

を超えたことを示すために、より適切であるかもしれませんそれらを文書化する必要があること。非標準的な使用がリソースごとに異なる場合は、すべてのリソースについて文書化する必要があることも意味します。

上記の間違いを避けると、自分の仕事を節約して、同時にユーザーの作業を楽にすることができます。