My app is using spring-data-rest
and spring-restdocs
.
My setup is really standard; copied from the docs almost entirely, but I've included the samples below in case I'm missing something.
When my mvc test runs, it fails with:
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"
}
}
}
This is my test code:
@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)
Here's the stack:
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)
How do I get spring-restdocs
and spring-data-rest
to play nice?
My documentation
instance is defined as follows:
ResultHandler documentation = document("items/findOne",
preprocessRequest(prettyPrint(), maskLinks()),
preprocessResponse(prettyPrint()),
responseFields(
fieldWithPath("name").description("Item name.")
// Bunch more
));
As @meistermeier indicated, (and following the restdocs docs for ignoring links, I can add
links(linkWithRel("self").ignored(),
linkWithRel("_self").ignored().optional()) // docs suggest this. /shrug
But that still leaves me with:
SnippetException: Links with the following relations were not documented: [item]
Seems like the _links
are always going to have that self-reference back to the same entity, right?
How do I cleanly handle this without ignoring an entity-specific link for every test, like:
links(linkWithRel("item").ignored())
Even if I do add the above line (so that all fields self
_self
curies
and item
are all ignored()
and/or optional()
), the result of the test returns to the original error at the top of this question.
Seems like the _links are always going to have that self-reference back to the same entity, right?
Yes, that's right.
I may have your solution for ignoring some links in a small github sample. Especially the part:
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")
)
));
where I completely ignore all "generated" fields and only create a documentation entry for the domain. Your item
link would be my beerapi:beer
.
I really don't know what is best practice here, but I would always document as much as possible since you can use asciidoctor links (like <<beer-links,Links>>
) wherever possible to reference other parts with more documentation.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With