Bean Validation API support about spring-restdocs HOT 7 CLOSED

Interesting suggestion. Thanks. I'm less opposed to reusing existing annotations, such as those for bean validation, than I am to adding annotations to your implementation specifically for the purposes of documentation.

I want to keep Spring REST docs as "stupid" as possible. I don't want it to try to discover your DTOs and exactly how they're validated as it'll inevitably get it wrong on occasion, lag behind validation features in the framework, etc. An explicit API that, for example, takes a class and a field name and extracts a description of the bean validation constraints would (largely) avoid these problems. I think it certainly warrants some exploration, particularly if others are interested in this functionality. +1s welcome.

from spring-restdocs.

👍

from spring-restdocs.

👍

from spring-restdocs.

👍

from spring-restdocs.

The fact that this is possible with the Bean Validation API makes me doubt the wisdom of trying to implement this.

from spring-restdocs.

@wilkinsona ouch! I do take your point. For sure libraries and languages can often be abused in interesting and sometimes unbelievable ways ;)

This suggestion really grew out of a desire to find a good way to document request body constraints in a way that is; easy for someone to understand, doesn't bloat the documentation too much and doesn't require developers to duplicate descriptions of declarative rules.

Sure, I can write tests that violate lots of different rules ( and if my response body conatins more descriptive messages that just "400 bad request", this will ensure that a meaningful response body ends up in the documentation), but as I pointed out above, I don't feel like this is good way for people to consume this data...

In my precise use-case JSON is the interchange format of choice, so I know there are solutions out there that might help document things like the schema. Some of these also support things like required and min/max lengths and so on. But, again these require additional annotations.

It'd be great to find a solution that can document the request body and the basic constraints without resorting to duplicating annotations or adding new ones just for the purpose of documentation. I understand not everyone will use bean-validation but, to me at least, supporting these seems like a fair idea since a standard library exists. I'd be keen to hear other ideas about the best way of doing this and thanks again for taking the time to read and consider this suggestion.

from spring-restdocs.

I like this idea very much and supporting a subset of the existing annotations (like Notnull, Regexp, Min, Max, Length ..) should work for 99% of the users.

from spring-restdocs.