Spring Restdocs是Spring restful 專案(spring-hateoas, spring-data-rest)專用的文件產生器. Spring Restdocs 的特色如下:

  • 專案必須符合REST 成熟度模型 level 3, 換句話說就是要使用HATEOAS
  • 文件的撰寫格式為 AsciiDoc, 輸出格式預設為 HTML
  • 變動性高的reqeust,response的內容使用 spring-mvc-test 驅動 test cases 產出asciidoctor格式的片段程式碼,之後可視需求 include 到主文件

試用了一陣子後，因為以下的原因不用了

  1. asciidoc 語法，過於彈性，讓文件多了很多非制式的語法，嚴重的降低了一致性跟可讀性
  2. 目前用的 frontend framework,extjs, 對heatos支援不好
  3. 文件寫法沒有像API Blueprint一樣的標準

API Blueprint新版的規格也快release了，所以還是換回了用 API Blueprint，但受到Spring Restdocs的啟發，寫了一個sprint mvc testcase -> markdown的功能， 有效的解決之前API Blueprint過到的難題。

Resources