The Spring REST Docs project helps you document RESTful services. It combines handwritten documentation written with Asciidoctor and autogenerated snippets produced with Spring MVC Test.

This is quite a different approach of other RESTful API documenting tools, such as Swagger, which separate the API documents from the API implementation. Usually, API designers write the API documents during the API design phase and then developers implement the API according to the API designs in the documents. One of the main drawbacks is that you will have to always remember to keep the document up-to-date with the latest implementation. Otherwise, developers of the API clients will see a non-working API, which causes confusion.

Spring REST Docs helps you produce API documentation that is accurate, concise, and well-structured. Every time you run mvn test, the document will be updated to the latest implementation. This generation of documents based on unit testing is a brilliant idea. It provides assurance that your API documentation will always be up-to-date and accurate. 

However, currently, at the time of writing this book, there are some drawbacks with Spring REST Docs. One of them is that it won't help you that much during the API design phase. You will still need to write API design documents, and there's a good chance that you might have to throw away the API design documents once you can generate the documentation from test cases. If you're working on a big project, this could mean that you will have to throw away or deprecate lots of efforts that you or the team put into the API design documents.

Another drawback is that, currently, there is no support for the API playground. Developers can read the documents but cannot interact with the API, which makes the API harder to use.  

Another drawback, which might be a problem for some developers, is that it doesn't support the OpenAPI specification (https://www.openapis.org). Hence, developers of API clients cannot generate the client code as they would with Swagger, which supports OpenAPI.

Still, Spring REST Docs is a great project and definitely worth trying. It is under active development at the time of writing this book.