代码之家 › 专栏 › 技术社区 › Eric J Turley

由于spring数据rest中的HAL“_links”元素导致restdocs代码段异常

spring-restdocs spring-data-rest spring java

Eric J Turley · 技术社区 · 8 年前

我的应用程序正在使用 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)

我怎么得到 SpringRestDocs 和 spring数据休息 玩得好吗?

我的 documentation 实例定义如下:

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

the restdocs docs for ignoring links 我可以补充说

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

但这仍然留给我:

SnippetException: Links with the following relations were not documented: [item]

似乎 _links 我们总是会将自我引用返回到同一实体,对吗? 如何在不忽略每个测试的实体特定链接的情况下干净地处理此问题,如:

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

做添加上述行(以便所有字段 self _self curies 和 item 都是 ignored() 和/或 optional() ),测试结果返回到问题顶部的原始错误。

2 回复 | 直到 8 年前

meistermeier 8 年前

是的,没错。

我可能有您的解决方案,可以忽略中的某些链接 a small github sample 尤其是部分:

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 .

<<beer-links,Links>> )在可能的情况下,参考更多文档的其他部分。

Alex Myers 6 年前

规范的方法似乎是使用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()
       ),