使用Spring REST文檔回覆文檔的狀態

Question

我正在使用Spring REST Docs爲我的REST風格的服務生成文檔，並且我想生成一個可能的帶有說明的響應狀態值表，如here（在底部的頁面）。

我可以在我的父母index.adoc文件中手動執行它，其中包括生成的文件，但我不喜歡它，因爲它使我的文檔散開，儘管我想將整個簽名描述保留在一個地方。

我已閱讀REST Docs文檔，並在StackOverflow和項目的GitHub問題上進行了搜索，但沒有看到任何此類功能。

我錯過了什麼，或者我正在尋找的功能沒有實現，甚至不需要？

Answer 1

你正在尋找的功能沒有實現，在我看來，它是不需要的。

當您正在開發和編寫RESTful API時，應該儘可能使您的API儘可能一致地使用HTTP狀態代碼，並且還應該使用標準的，每種狀態的理解含義。如果遵循這兩條準則，則可以避免完全記錄狀態代碼，也可以在概覽部分中記錄一次。

你鏈接到提供什麼，我不認爲你應該做的幾個例子的文檔：

1. 它記錄了一個200表示請求成功。這是200響應的標準含義，因此文檔很少添加
2. 402用於​​阻塞的API密鑰，但實際上它意味着需要付款。阿403（禁止）響應可能是更合適的
3. 它濫用404（未找到），以指示一個速率限制已被超過

總之，使得不規範使用的HTTP狀態代碼意味着他們需要記錄。如果非標準使用因資源而異，那麼這也意味着它們需要記錄在每個資源中。

如果您避免犯上述錯誤，您可以節省自己的一些工作，同時讓用戶更容易。