restdocs SnippetException из-за элементов HAL "_links" из spring-data-rest

Мое приложение использует 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 хорошо играть?

EDIT (S):

мойdocumentationэкземпляр определяется следующим образом:

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

Как указал @meistermeier (и, следуя документам restdocs за игнорирование ссылок, я могу добавить

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

Но это все еще оставляет меня с:

SnippetException: ссылки со следующими отношениями не были задокументированы: [item]

Похоже на_linksвсегда будет иметь эту ссылку на себя обратно к той же сущности, верно? Как мне аккуратно обработать это, не игнорируя объектно-ориентированную ссылку для каждого теста, например:

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

Даже если я добавлю вышеупомянутую строку (так, чтобы все поля self_selfcuries а также item являются все ignored() и / или optional()), результат теста возвращается к исходной ошибке в верхней части этого вопроса.

Источник

1 ответ

Решение

Похоже, у _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>>) где это возможно, чтобы ссылаться на другие части с большим количеством документации.

Источник

Каноническим способом кажется использование вещей из документации restdocs. Подход соответствует подходу из решения meistermeier.

Документация может быть найдена в https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

Образец кода:

.consumeWith(document("items",
       links(
               halLinks(), // <- this shorten things a bit
               linkWithRel("self").ignored(),
               linkWithRel("profile").ignored()
       ),
Источник
Другие вопросы по тегам