The aim of Spring REST Docs is to help you produce accurate and readable documentation for your RESTful services.spring-doc.cn

Writing high-quality documentation is difficult. One way to ease that difficulty is to use tools that are well-suited to the job. To this end, Spring REST Docs uses Asciidoctor by default. Asciidoctor processes plain text and produces HTML, styled and laid out to suit your needs. If you prefer, you can also configure Spring REST Docs to use Markdown.spring-doc.cn

Spring REST Docs uses snippets produced by tests written with Spring MVC’s test framework, Spring WebFlux’s WebTestClient or REST Assured 5. This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect, the test that produces it fails.spring-doc.cn

Documenting a RESTful service is largely about describing its resources. Two key parts of each resource’s description are the details of the HTTP requests that it consumes and the HTTP responses that it produces. Spring REST Docs lets you work with these resources and the HTTP requests and responses, shielding your documentation from the inner-details of your service’s implementation. This separation helps you document your service’s API rather than its implementation. It also frees you to evolve the implementation without having to rework the documentation.spring-doc.cn