将手写文档与通过 Spring MVC 测试、WebTestClient 或 Rest Assured 生成的自动生成的片段结合在一起来实现文档服务。
## [导言](#introduction)
Spring REST DOCS 的目的是帮助你为 RESTful 服务生成准确且可读的文档。
编写高质量的文档是困难的。减轻这一困难的一种方法是使用非常适合这项工作的工具。为此, Spring REST DOCS 默认使用[ASCIIDoctor](https://asciidoctor.org)。ASCIIDoctor 处理纯文本并生成 HTML,并根据你的需要进行样式和布局。如果你愿意,还可以将 Spring REST DOCS 配置为使用 Markdown。
Spring REST DOCS 使用由用 Spring MVC 的、 Spring WebFlux 的[](https://DOCS. Spring.io/ Spring-Framework/DOCS/5.0.x/ Spring-Framework-Reference/Testing.html#WebTestClient)或编写的测试产生的代码片段。这种测试驱动的方法有助于保证服务文档的准确性。如果代码片段不正确,则生成它的测试失败。
|[Spring Data REST](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/rest-notes-spring-data-rest)| Maven |演示如何为使用[Spring Data REST](https://projects.spring.io/spring-data-rest/)实现的服务创建入门指南和 API 指南。|
| [Spring HATEOAS](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/rest-notes-spring-hateoas) | Gradle |演示如何为使用[Spring HATEOAS](https://projects.spring.io/spring-hateoas/)实现的服务创建入门指南和 API 指南。|
|[WebTestClient](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/web-test-client)| Gradle |Demonstrates the use of Spring REST docs with Spring WebFlux’s WebTestClient.|
|[放心吧](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/rest-assured)| Gradle |Demonstrates the use of Spring REST Docs with [放心吧](http://rest-assured.io).|
|[Slate](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/rest-notes-slate)| Gradle |Demonstrates the use of Spring REST Docs with Markdown and[Slate](https://github.com/tripit/slate).|
|[TestNG](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/testng)| Gradle | Demonstrates the use of Spring REST Docs with [TestNG](http://testng.org). |
|[JUnit 5](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/junit5)| Gradle | Demonstrates the use of Spring REST Docs with [JUnit 5](https://junit.org/junit5/). |
使用 Spring REST DOCS 的第一步是配置项目的构建。[Spring HATEOAS](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/rest-notes-spring-hateoas)和[Spring Data REST](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/rest-notes-spring-data-rest)样本分别包含一个`build.gradle`和`pom.xml`,你可能希望将其用作参考。配置的关键部分在以下清单中进行了描述:
你可能希望将生成的文档打包到项目的 JAR 文件中——例如,在 Spring 启动时将其[用作静态内容](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-spring-mvc-static-content)。要做到这一点,请配置项目的构建,以便:
Spring REST DOCS 使用 Spring MVC 的, Spring WebFlux 的[](https://DOCS. Spring.io/ Spring-Framework/DOCS/5.0.x/ Spring-Framework-Reference/Testing.html#WebTestClient),或向你正在记录的服务发出请求。然后,它为请求和结果响应生成文档片段。
在使用 HAL 时,你可能希望在概述部分对它们进行一次文档记录,然后在 API 文档的其余部分中忽略它们,而不是对每个响应都通用的链接进行文档记录,例如`self`和`curies`。为此,你可以构建[支持重用代码片段](#documenting-your-api-reusing-snippets),将链接描述符添加到预先配置为忽略某些链接的片段中。下面的示例展示了如何做到这一点:
```
public static LinksSnippet links(LinkDescriptor... descriptors) {
|**1**|配置 Spring REST DOCS 以生成描述响应有效负载中的字段的片段。<br/>要记录请求,可以使用`requestFields`。<br/>都是`org.springframework.restdocs.payload.PayloadDocumentation`上的静态方法。|
要重写缺省描述或提供新的描述,你可以创建一个基名为`org.springframework.restdocs.constraints.ConstraintDescriptions`的资源包。 Spring 基于 Hateoas 的样本包含[这样的资源包的一个例子](https://github.com/spring-projects/spring-restdocs/tree/v2.0.6.RELEASE/samples/rest-notes-spring-hateoas/src/test/resources/org/springframework/restdocs/constraints/ConstraintDescriptions.properties)。
Spring REST DOCS 使用模板来产生所生成的片段。是为 Spring REST DOCS 能够产生的每个片段提供的。要定制片段的内容,你可以提供自己的模板。
模板是从 Classpath 从`org.springframework.restdocs.templates`子包中加载的。子包的名称由所使用的模板格式的 ID 确定。默认的模板格式 ASCIIDoctor 的 ID 为`asciidoctor`,因此从`org.springframework.restdocs.templates.asciidoctor`加载片段。每个模板都以其生成的代码片段命名。例如,要覆盖`curl-request.adoc`片段的模板,请在`src/test/resources/org/springframework/restdocs/templates/asciidoctor`中创建一个名为`curl-request.snippet`的模板。
如果你希望对 Spring REST DOCS 进行增强,那么最受欢迎的是拉请求。源代码位于[GitHub](https://github.com/spring-projects/spring-restdocs)上。你可能希望搜索[现有问题](https://github.com/spring-projects/spring-restdocs/issues?q=is%3Aissue)和[拉请求](https://github.com/spring-projects/spring-restdocs/pulls?q=is%3Apr),以查看是否已经提出了增强。你可能还希望[打开新的一期](https://github.com/spring-projects/spring-restdocs/issues/new)在开始工作之前讨论可能的增强。