Spring REST Docs

https://docs.spring.io/spring-restdocs/docs/2.0.1.RELEASE/reference/html5/

Spring REST Docs

通过将手写文档与使用Spring MVC测试生成的自动生成的片段相结合来记录RESTful服务。

介绍

Spring REST Docs的目标是帮助您为您的RESTful服务生成准确可读的文档。

编写高质量的文档很困难。减轻这种困难的一种方法是使用非常适合工作的工具。为此，Spring REST Docs 默认使用Asciidoctor。Asciidoctor处理纯文本并生成HTML，进行样式化和布局以满足您的需求。如果您愿意，还可以将Spring REST Docs配置为使用Markdown。

Spring REST Docs利用Spring MVC的测试框架 Spring WebFlux WebTestClient或 REST Assured 3编写的测试生成的代码片段。这种测试驱动的方法有助于保证服务文档的准确性。如果代码片段不正确，则生成它的测试将失败。

记录RESTful服务主要是描述其资源。每个资源描述的两个关键部分是它消耗的HTTP请求的细节以及它产生的HTTP响应。Spring REST Docs允许您使用这些资源以及HTTP请求和响应，从而将文档从服务实现的内部细节中屏蔽掉。这种分离可以帮助你记录你的服务的API而不是它的实现。它还可以让您在不重写文档的情况下发展实现。