9

我的应用程序正在使用spring-data-rest和spring-restdocs。我的设置非常标准；几乎完全从文档中复制，但我已经包含了下面的示例，以防我遗漏了一些东西。当我的 mvc 测试运行时，它失败了：

org.springframework.restdocs.snippet.SnippetException: The following parts of the payload were not documented:
{
  "_links" : {
    "self" : {
      "href" : "https://my-api/item/10"
    },
    "item" : {
      "href" : "https://my-api/item/10"
    }
  }
}

这是我的测试代码：

@Rule
public JUnitRestDocumentation restDocs = new JUnitRestDocumentation("target/generated-snippets");
// ...
mockMvc = webAppContextSetup(wac) //WebApplicationContext
        .apply(documentationConfiguration(restDocs)
                       .uris()
                       .withHost("my-api")
                       .withPort(443)
                       .withScheme("https"))
        .build();
// ....
mockMvc.perform(get("/items/{id}", "10"))
               .andDo(documentation)

这是堆栈：

at org.springframework.restdocs.payload.AbstractFieldsSnippet.validateFieldDocumentation(AbstractFieldsSnippet.java:176)
at org.springframework.restdocs.payload.AbstractFieldsSnippet.createModel(AbstractFieldsSnippet.java:100)
at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:64)
at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:196)
at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:55)
at org.springframework.test.web.servlet.MockMvc$1.andDo(MockMvc.java:177)
at com.example.my.api.domain.MyRepositoryRestTest.findOne(MyRepositoryRestTest.java:36)

我如何获得spring-restdocs并spring-data-rest玩得好？

编辑：

我的documentation实例定义如下：

ResultHandler documentation = document("items/findOne",
                                       preprocessRequest(prettyPrint(), maskLinks()),
                                       preprocessResponse(prettyPrint()),
                                       responseFields(
                                            fieldWithPath("name").description("Item name.")
                                            // Bunch more
                                       ));

正如@meistermeier 指出的那样，（并遵循restdocs docs for ignoring links，我可以添加

links(linkWithRel("self").ignored(),
      linkWithRel("_self").ignored().optional()) // docs suggest this. /shrug

但这仍然给我留下了：

SnippetException：未记录具有以下关系的链接：[项目]

似乎_links总是会将自我引用返回到同一个实体，对吧？如何在不忽略每个测试的实体特定链接的情况下干净地处理这个问题，例如：

links(linkWithRel("item").ignored())

即使我确实添加了上面的行（以便所有字段self _self curies和item都是ignored()和/或optional()），测试结果也会返回到该问题顶部的原始错误。

4

2 回答 2

8

似乎 _links 总是会将自引用返回到同一个实体，对吗？

是的，这是正确的。

我可能有你的解决方案来忽略一个小的 github 示例中的一些链接。特别是部分：

mockMvc.perform(RestDocumentationRequestBuilders.get(beerLocation)).andExpect(status().isOk())
       .andDo(document("beer-get", links(
                linkWithRel("self").ignored(),
                linkWithRel("beerapi:beer").description("The <<beers, Beer resource>> itself"),
                linkWithRel("curies").ignored()
               ),
               responseFields(
                  fieldWithPath("name").description("The name of the tasty fresh liquid"),
                  fieldWithPath("_links").description("<<beer-links,Links>> to other resources")
               )
            ));

我完全忽略所有“生成”字段，只为域创建一个文档条目。您的item链接将是我的beerapi:beer。

我真的不知道这里的最佳实践是什么，但我总是会尽可能多地记录，因为您可以尽可能使用 asciidoctor 链接（如<<beer-links,Links>>）来引用其他部分的更多文档。

于 2016-12-13T08:21:09.773 回答
0

规范的方式似乎是使用来自 restdocs 文档的东西。方法与https://stackoverflow.com/users/2650436/meistermeier解决方案中的方法一致。

文档可以在https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api-hypermedia-link-formats上找到

示例代码：

.consumeWith(document("items",
       links(
               halLinks(), // <- this shorten things a bit
               linkWithRel("self").ignored(),
               linkWithRel("profile").ignored()
       ),
于 2019-05-30T14:26:58.763 回答