Bean Validation API support

[davidgoate]

I understand that this project was partially created out of the authors frustration with tools like Swagger and annotation processing. I also like the test-driven approach to producing documentation.

I'd like to propose an enhancement to allow for a limited amount of annotation processing. Specifically, for the Bean Validation API and Hibernate Validator annotations.

When documenting an API using the "test-driven" approach I think it's potentially tricky to try and document what the request body should look like and what the constraints on each field are.

One can, and should, write tests that verify that the app does reject invalid values for each field, e.g. invalid email format, missing required fields, too long/short data etc... It would also be a good idea to test an example of a "good" request (and therefore automatically have it documented). However, when producing documentation, showing people all the possible ways a request could be wrong doesn't sound like the best way. It would be nicer to show an example of a "good" request and then explain what the basic validation rules are (clearly there will often be validation which isn't expressed using the bean validation API and these may warrant explicit hand written documentation).

The problem with writing this sort of information into the asciidoc file directly, is that as soon as any validation rules change the docs are immediately out-of-date (DRY/SSOT). This seems a shame given that often a lot of the basic rules are easily expressed declaratively with the bean validation annotations.

I don't necessarily know what the "best" way of doing this would be. But to prevent having to discover which Objects need to be parsed the feature could require the documentation code to pass the class object (TestRequest.class in the example below) to some kind of processor in spring-restdoc. It could produce an asciidoc file in the snippets output directory that contained a table describing the rules.

Example

Controller Method

    @RequestMapping(value = ... , method = ..., consumes = ...)
    public ResponseEntity<TestResult> test(@RequestBody TestRequest requestBody) {
        ...
    }

Request Body

public class TestRequest {
    @NotBlank
    @Length(min = 1, max = 2_000)
    private String field1;

    @Email
    @NotBlank
    @Length(max = 254)
    private String field2;

    @Length(min = 5, max = 20)
    private String field3;

    @NotNull
    private Boolean field4;

   // constructors, getters, setters etc...
}

Sample Output

|===
|Field  |Mandatory |Validation Rules

|field1
|Yes
|Length 1 - 2,000

|field2
|Yes
|Valid email format, max length 254

|field3
|No
|Length 5 - 20

|field4
|Yes
|true/false
|===

Such a snippet could then be included in the documentation as usual include::{generated}/request-body.asciidoc[]

I don't suggest processing the controller to try and "auto-discover" the correct endpoint, supported media types, HTTP methods, response codes or which objects form the request body and so on.

[wilkinsona]

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.

[theonlyguills]

👍

[firefoxNX]

👍

👍

[wilkinsona]

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

[davidgoate]

@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.

[jtheuer]

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.