使用 REST Docs

你可以使用 Spring REST Docs 通过 Spring MockMvc、WebTestClient 或 RestAssured 为 HTTP API 生成文档（例如，Asciidoc 格式）。在生成 API 文档的同时，你还可以使用 Spring Cloud Contract WireMock 生成 WireMock 存根。为此，编写你常规的 REST Docs 测试用例，并使用 @AutoConfigureRestDocs 在 REST Docs 输出目录中自动生成存根。下面的 UML 图显示了 REST Docs 的流程

rest-docs

以下示例使用了 MockMvc

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureRestDocs(outputDir = "target/snippets")
@AutoConfigureMockMvc
public class ApplicationTests {

	@Autowired
	private MockMvc mockMvc;

	@Test
	public void contextLoads() throws Exception {
		mockMvc.perform(get("/resource"))
				.andExpect(content().string("Hello World"))
				.andDo(document("resource"));
	}
}

此测试会在 target/snippets/stubs/resource.json 生成一个 WireMock 存根。它匹配所有针对 /resource 路径的 GET 请求。使用 WebTestClient（用于测试 Spring WebFlux 应用）的相同示例如下

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureRestDocs(outputDir = "target/snippets")
@AutoConfigureWebTestClient
public class ApplicationTests {

	@Autowired
	private WebTestClient client;

	@Test
	public void contextLoads() throws Exception {
		client.get().uri("/resource").exchange()
				.expectBody(String.class).isEqualTo("Hello World")
 				.consumeWith(document("resource"));
	}
}

无需任何额外配置，这些测试会创建一个带有请求匹配器的存根，用于匹配 HTTP 方法以及除 host 和 content-length 外的所有头部。为了更精确地匹配请求（例如，匹配 POST 或 PUT 的请求体），我们需要显式地创建一个请求匹配器。这样做有两个效果

  • 创建一个仅按你指定方式匹配的存根。

  • 断言测试用例中的请求也匹配相同的条件。

此特性的主要入口点是 WireMockRestDocs.verify()，它可以作为 document() 便利方法的替代，如下例所示

import static org.springframework.cloud.contract.wiremock.restdocs.WireMockRestDocs.verify;

@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureRestDocs(outputDir = "target/snippets")
@AutoConfigureMockMvc
public class ApplicationTests {

	@Autowired
	private MockMvc mockMvc;

	@Test
	public void contextLoads() throws Exception {
		mockMvc.perform(post("/resource")
                .content("{\"id\":\"123456\",\"message\":\"Hello World\"}"))
				.andExpect(status().isOk())
				.andDo(verify().jsonPath("$.id"))
				.andDo(document("resource"));
	}
}

前面的契约指定了任何带有 id 字段的有效 POST 请求都会接收此测试中定义的响应。你可以链接调用 .jsonPath() 来添加更多匹配器。如果你不熟悉 JSON Path，JayWay 文档 可以帮助你快速入门。WebTestClient 版本的此测试有一个类似的 verify() 静态帮助方法，你可以将其插入到相同位置。

除了 jsonPath 和 contentType 便利方法外，你还可以使用 WireMock API 来验证请求是否匹配创建的存根，如下例所示

@Test
public void contextLoads() throws Exception {
	mockMvc.perform(post("/resource")
               .content("{\"id\":\"123456\",\"message\":\"Hello World\"}"))
			.andExpect(status().isOk())
			.andDo(verify()
					.wiremock(WireMock.post(urlPathEquals("/resource"))
					.withRequestBody(matchingJsonPath("$.id"))
					.andDo(document("post-resource"))));
}

WireMock API 功能丰富。你可以通过正则表达式以及 JSON path 匹配头部、查询参数和请求体。你可以使用这些特性创建包含更广泛参数的存根。前面的示例生成了一个类似于下面示例的存根

post-resource.json
{
  "request" : {
    "url" : "/resource",
    "method" : "POST",
    "bodyPatterns" : [ {
      "matchesJsonPath" : "$.id"
    }]
  },
  "response" : {
    "status" : 200,
    "body" : "Hello World",
    "headers" : {
      "X-Application-Context" : "application:-1",
      "Content-Type" : "text/plain"
    }
  }
}
你可以使用 wiremock() 方法或 jsonPath() 和 contentType() 方法来创建请求匹配器，但不能同时使用这两种方法。

在消费者侧，你可以将本节前面生成的 resource.json 文件在类路径中可用（例如，通过将存根发布为 JAR）。之后，你可以通过多种不同方式创建一个使用 WireMock 的存根，包括使用 @AutoConfigureWireMock(stubs="classpath:resource.json")，如本文档前面所述。

使用 REST Docs 生成契约

你还可以使用 Spring REST Docs 生成 Spring Cloud Contract DSL 文件和文档。如果将其与 Spring Cloud WireMock 结合使用，你将同时获得契约和存根。

为什么会想要使用此功能？社区中的一些人问到了这样的情况：他们希望转向基于 DSL 的契约定义，但他们已经有很多 Spring MVC 测试。使用此功能可以让你生成契约文件，你以后可以修改并将它们移动到文件夹（在你的配置中定义），以便插件能够找到它们。

你可能想知道为什么此功能在 WireMock 模块中。此功能在那里是因为同时生成契约和存根是有意义的。

考虑以下测试

		this.mockMvc
			.perform(post("/foo").accept(MediaType.APPLICATION_PDF)
				.accept(MediaType.APPLICATION_JSON)
				.contentType(MediaType.APPLICATION_JSON)
				.content("{\"foo\": 23, \"bar\" : \"baz\" }"))
			.andExpect(status().isOk())
			.andExpect(content().string("bar"))
			// first WireMock
			.andDo(WireMockRestDocs.verify()
				.jsonPath("$[?(@.foo >= 20)]")
				.jsonPath("$[?(@.bar in ['baz','bazz','bazzz'])]")
				.contentType(MediaType.valueOf("application/json")))
			// then Contract DSL documentation
			.andDo(document("index", SpringCloudContractRestDocs.dslContract(Maps.of("priority", 1))));

前面的测试创建了上一节中展示的存根，同时生成了契约和文档文件。

契约文件名为 index.groovy，可能类似于以下示例

import org.springframework.cloud.contract.spec.Contract

Contract.make {
    request {
        method 'POST'
        url '/foo'
        body('''
            {"foo": 23 }
        ''')
        headers {
            header('''Accept''', '''application/json''')
            header('''Content-Type''', '''application/json''')
        }
    }
    response {
        status OK()
        body('''
        bar
        ''')
        headers {
            header('''Content-Type''', '''application/json;charset=UTF-8''')
            header('''Content-Length''', '''3''')
        }
        bodyMatchers {
            jsonPath('$[?(@.foo >= 20)]', byType())
        }
    }
}

生成的文档（在本例中格式为 Asciidoc）包含格式化的契约。此文件的位置将是 index/dsl-contract.adoc。

指定 priority 属性

方法 SpringCloudContractRestDocs.dslContract() 接受一个可选的 Map 参数，允许你在模板中指定附加属性。

其中一个属性是 priority 字段，你可以按如下方式指定

SpringCloudContractRestDocs.dslContract(Map.of("priority", 1))

覆盖 DSL 契约模板

默认情况下，契约的输出基于一个名为 default-dsl-contract-only.snippet 的文件。

你可以通过按如下方式覆盖 getTemplate() 方法来提供自定义模板文件

new ContractDslSnippet(){
    @Override
    protected String getTemplate() {
        return "custom-dsl-contract";
    }
}));

因此，上面显示此行的示例

.andDo(document("index", SpringCloudContractRestDocs.dslContract()));

应更改为

.andDo(document("index", new ContractDslSnippet(){
                            @Override
                            protected String getTemplate() {
                                return "custom-dsl-template";
                            }
                        }));

模板通过查找类路径上的资源来解析。按以下顺序检查以下位置

  • org/springframework/restdocs/templates/${templateFormatId}/${name}.snippet

  • org/springframework/restdocs/templates/${name}.snippet

  • org/springframework/restdocs/templates/${templateFormatId}/default-${name}.snippet

因此，在上面的示例中，你应该将名为 custom-dsl-template.snippet 的文件放在 src/test/resources/org/springframework/restdocs/templates/custom-dsl-template.snippet 路径下