Provide an API to ease documenting a request field’s constraints

Previously, users that wanted to document a request field’s constraints
had to roll their own solution. This commit introduces a new API that
makes it easier to document constraints. Support is provided for
discovering Bean Validation constraints and resolving descriptions for
them. The constraint descriptions can then be used as required. For
example, they can included in a field’s description or in an additional
constraints attribute that’s included in an additional table column via
the use of a custom snippet template.

Closes gh-42

samples/rest-notes-spring-hateoas/src/main/java/com/example/notes/AbstractNoteInput.java

@@ -1,51 +0,0 @@
-/*
- * Copyright 2014 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.example.notes;
-
-import java.net.URI;
-import java.util.Collections;
-import java.util.List;
-
-import com.fasterxml.jackson.annotation.JsonProperty;
-
-abstract class AbstractNoteInput {
-
-	private final String title;
-
-	private final String body;
-
-	private final List<URI> tagUris;
-
-	public AbstractNoteInput(String title, String body, List<URI> tagUris) {
-		this.title = title;
-		this.body = body;
-		this.tagUris = tagUris == null ? Collections.<URI> emptyList() : tagUris;
-	}
-
-	public String getTitle() {
-		return title;
-	}
-
-	public String getBody() {
-		return body;
-	}
-
-	@JsonProperty("tags")
-	public List<URI> getTagUris() {
-		return this.tagUris;
-	}
-}

samples/rest-notes-spring-hateoas/src/main/java/com/example/notes/AbstractTagInput.java

@@ -1,31 +0,0 @@
-/*
- * Copyright 2014 the original author or authors.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package com.example.notes;
-
-
-abstract class AbstractTagInput {
-
-	private final String name;
-
-	public AbstractTagInput(String name) {
-		this.name = name;
-	}
-
-	public String getName() {
-		return name;
-	}
-}

samples/rest-notes-spring-hateoas/src/main/java/com/example/notes/NoteInput.java

@@ -17,6 +17,7 @@
 package com.example.notes;
 
 import java.net.URI;
+import java.util.Collections;
 import java.util.List;
 
 import org.hibernate.validator.constraints.NotBlank;
@@ -24,11 +25,34 @@ import org.hibernate.validator.constraints.NotBlank;
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
-public class NoteInput extends AbstractNoteInput {
+public class NoteInput {
+	
+	@NotBlank
+	private final String title;
+
+	private final String body;
+
+	private final List<URI> tagUris;
 
 	@JsonCreator
-	public NoteInput(@NotBlank @JsonProperty("title") String title,
+	public NoteInput(@JsonProperty("title") String title,
 			@JsonProperty("body") String body, @JsonProperty("tags") List<URI> tagUris) {
-		super(title, body, tagUris);
+		this.title = title;
+		this.body = body;
+		this.tagUris = tagUris == null ? Collections.<URI>emptyList() : tagUris;
 	}
+
+	public String getTitle() {
+		return title;
+	}
+
+	public String getBody() {
+		return body;
+	}
+
+	@JsonProperty("tags")
+	public List<URI> getTagUris() {
+		return this.tagUris;
+	}
+
 }

samples/rest-notes-spring-hateoas/src/main/java/com/example/notes/NotePatchInput.java

@@ -17,16 +17,39 @@
 package com.example.notes;
 
 import java.net.URI;
+import java.util.Collections;
 import java.util.List;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
-public class NotePatchInput extends AbstractNoteInput {
+public class NotePatchInput {
+	
+	@NullOrNotBlank 
+	private final String title;
+	
+	private final String body;
+	
+	private final List<URI> tagUris;
 
 	@JsonCreator
-	public NotePatchInput(@NullOrNotBlank @JsonProperty("title") String title,
+	public NotePatchInput(@JsonProperty("title") String title,
 			@JsonProperty("body") String body, @JsonProperty("tags") List<URI> tagUris) {
-		super(title, body, tagUris);
+		this.title = title;
+		this.body = body;
+		this.tagUris = tagUris == null ? Collections.<URI>emptyList() : tagUris;
+	}
+	
+	public String getTitle() {
+		return title;
+	}
+
+	public String getBody() {
+		return body;
+	}
+
+	@JsonProperty("tags")
+	public List<URI> getTagUris() {
+		return this.tagUris;
 	}
 }

samples/rest-notes-spring-hateoas/src/main/java/com/example/notes/NullOrNotBlank.java

@@ -17,18 +17,30 @@
 package com.example.notes;
 
 import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-import javax.validation.constraints.NotNull;
+import javax.validation.Constraint;
+import javax.validation.Payload;
+import javax.validation.constraints.Null;
 
 import org.hibernate.validator.constraints.CompositionType;
 import org.hibernate.validator.constraints.ConstraintComposition;
 import org.hibernate.validator.constraints.NotBlank;
 
 @ConstraintComposition(CompositionType.OR)
-@NotNull
+@Constraint(validatedBy = {})
+@Null
 @NotBlank
 @Target({ ElementType.FIELD, ElementType.PARAMETER })
+@Retention(RetentionPolicy.RUNTIME)
 public @interface NullOrNotBlank {
 
+	String message() default "Must be null or not blank";
+
+	Class<?>[] groups() default {};
+
+	Class<? extends Payload>[] payload() default {};
+
 }

samples/rest-notes-spring-hateoas/src/main/java/com/example/notes/TagInput.java

@@ -21,10 +21,18 @@ import org.hibernate.validator.constraints.NotBlank;
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
-public class TagInput extends AbstractTagInput {
+public class TagInput {
+
+	@NotBlank
+	private final String name;
 
 	@JsonCreator
 	public TagInput(@NotBlank @JsonProperty("name") String name) {
-		super(name);
+		this.name = name;
 	}
+
+	public String getName() {
+		return name;
+	}
+
 }

samples/rest-notes-spring-hateoas/src/main/java/com/example/notes/TagPatchInput.java

@@ -19,10 +19,18 @@ package com.example.notes;
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
-public class TagPatchInput extends AbstractTagInput {
+public class TagPatchInput {
+	
+	@NullOrNotBlank
+	private final String name;
 
 	@JsonCreator
 	public TagPatchInput(@NullOrNotBlank @JsonProperty("name") String name) {
-		super(name);
+		this.name = name;
 	}
-}
+
+	public String getName() {
+		return name;
+	}
+	
+}