Adding constraints to PayloadDocumentation.fieldWithPath

[florind]

I am using the helper class https://github.com/spring-projects/spring-restdocs/blob/master/samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java#L393 to add constraints to the fields I'm documenting. It would be nice to have these constraints implicitly populated via the call to PayloadDocumentation.fieldWithPath and readily available for rendering.

[wilkinsona]

@florind Sorry, I don't think I understand your suggestion. Can you please expand a bit on how you think it could be done implicitly?

A little background here might be of interest. REST Docs deliberately has no knowledge of the constraints or where they come from and doesn't attempt to figure it out. Mapping between a field path and a particularly property on a particular class has to be done manually as I don't want REST Docs to get into the business of making a poor attempt at guessing the constraints.

[wilkinsona]

I should also have mentioned #106. My idea there is to have you still manually create the constraint descriptions for the classes the make up the response, but to then allow a field path to be used to traverse the ContraintDescriptions objects and get the relevant descriptions. Perhaps that's the sort of thing you're looking for?

[florind]

Thanks for the background @wilkinsona. The idea is to make constraint descriptions available similarly to types or attribute names. I'm not sure I follow the argument that the framework deliberately has no knowledge of the constraints. It already can describe them (http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#documenting-your-api-constraints-describing) and as well, properly display them (the Constraints field in request-fields.adoc). The test class I linked (part of Spring REST Docs test suite) provides a mechanism to have these constraints available for the framework to fill the respective Constraints column in the request-fields.adoc and it feels logical to provide out-of-the box support for describing constraints.

106 talks about nesting and it's not directly related with this (although it's a nice addition).

I hope this helps..

[wilkinsona]

Sorry, I don't think I explained myself very well. The key thing is that REST Docs makes no attempt to automatically figure out where the constraints have come from and how any constraints declared on a DTO map to constraints on a field in a request or response payload. I believe that it's an impossible task to figure it out automatically and be sufficiently accurate. For that reason, REST Docs provides a helper class that you can use to have constraint descriptions extracted from a DTO. It's then up to you to map each of those descriptions onto the appropriate field in the payload. The code that you've noticed in the sample is one example of performing this mapping, however it is not generally applicable so it doesn't belong in Spring REST Docs itself.