發布/記錄Spring-REST API

Question

我已經在stackoverflow和google上瀏覽了一下，但是找不到任何可以記錄SPRING-REST api的好工具。 嘗試使用enunciate，但是在無法識別的spring注釋上倒轉。 有誰知道一個很好的工具來記錄spring RESTful api？

Answer 1

嘗試使用Swagger。 它提供了一些自己的注釋，這些注釋無法與Spring MVC其余注釋一起使用。

Answer 2

通常，您無需記錄REST API。 應該為您的客戶提供所用媒體類型的規范（例如Atom或OpenSearch），並且僅依賴那里提供的信息。

一旦您記錄了有關特定服務的任何內容，就會將客戶與該文檔（和該服務）聯系起來。 結果是您的服務的發展能力現在受到客戶端在其代碼中烘烤的帶外信息量的限制（基於您的API描述）。

IOW-上一次您需要服務API描述來使Feed閱讀器與AtomPub服務對話是什么時候？

一月

PS我在[1]中總結了理論背景。 專門研究HTTP Type I / II和REST之間的區別。 而羅伊（Roy）的書（2）對此必讀。

[1] http://www.nordsc.com/ext/classification_of_http_based_apis.html [2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-Hypertext-driven

Answer 3

只需從客戶開發人員的角度記錄所有需要記錄的內容。 並且，請不要認真考慮“您無需記錄REST API”之類的建議。 這是一種學問指導，在現實世界中沒有用。

從客戶端開發人員的角度來看，每個成功的API都有詳盡的文檔記錄。 根植於學究觀念的任何API都將關閉客戶端開發人員。

有關某些示例，請參見我的“ RESTful Web服務指南”（http://shop.oreilly.com/product/9780596801694.do）的第14章。