fix(binding): Expose validator engine used by the default Validator (#1277)

* fix(binding): Expose validator engine used by the default Validator

- Add func ValidatorEngine for returning the underlying validator engine used
  in the default StructValidator implementation.
- Remove the function RegisterValidation from the StructValidator interface
  which made it immpossible to use a StructValidator implementation without the
  validator.v8 library.
- Update and rename test for registering validation
  Test{RegisterValidation => ValidatorEngine}.
- Update readme and example for registering custom validation.
- Add example for registering struct level validation.
- Add documentation for the following binding funcs/types:
  - Binding interface
  - StructValidator interface
  - Validator instance
  - Binding implementations
  - Default func

* fix(binding): Move validator engine getter inside interface

* docs: rm date cmd from custom validation demo

examples/custom-validation/server.go

@@ -30,7 +30,11 @@ func bookableDate(
 
 func main() {
 	route := gin.Default()
-	binding.Validator.RegisterValidation("bookabledate", bookableDate)
+
+	if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
+		v.RegisterValidation("bookabledate", bookableDate)
+	}
+
 	route.GET("/bookable", getBookable)
 	route.Run(":8085")
 }

examples/struct-lvl-validations/README.md

@@ -0,0 +1,50 @@
+## Struct level validations
+
+Validations can also be registered at the `struct` level when field level validations
+don't make much sense. This can also be used to solve cross-field validation elegantly.
+Additionally, it can be combined with tag validations. Struct Level validations run after
+the structs tag validations.
+
+### Example requests
+
+```shell
+# Validation errors are generated for struct tags as well as at the struct level
+$ curl -s -X POST http://localhost:8085/user \
+	-H 'content-type: application/json' \
+	-d '{}' | jq
+{
+  "error": "Key: 'User.Email' Error:Field validation for 'Email' failed on the 'required' tag\nKey: 'User.FirstName' Error:Field validation for 'FirstName' failed on the 'fnameorlname' tag\nKey: 'User.LastName' Error:Field validation for 'LastName' failed on the 'fnameorlname' tag",
+  "message": "User validation failed!"
+}
+
+# Validation fails at the struct level because neither first name nor last name are present
+$ curl -s -X POST http://localhost:8085/user \
+    -H 'content-type: application/json' \
+	-d '{"email": "george@vandaley.com"}' | jq
+{
+  "error": "Key: 'User.FirstName' Error:Field validation for 'FirstName' failed on the 'fnameorlname' tag\nKey: 'User.LastName' Error:Field validation for 'LastName' failed on the 'fnameorlname' tag",
+  "message": "User validation failed!"
+}
+
+# No validation errors when either first name or last name is present
+$ curl -X POST http://localhost:8085/user \
+    -H 'content-type: application/json' \
+	-d '{"fname": "George", "email": "george@vandaley.com"}'
+{"message":"User validation successful."}
+
+$ curl -X POST http://localhost:8085/user \
+    -H 'content-type: application/json' \
+	-d '{"lname": "Contanza", "email": "george@vandaley.com"}'
+{"message":"User validation successful."}
+
+$ curl -X POST http://localhost:8085/user \
+    -H 'content-type: application/json' \
+	-d '{"fname": "George", "lname": "Costanza", "email": "george@vandaley.com"}'
+{"message":"User validation successful."}
+```
+
+### Useful links
+
+- Validator docs - https://godoc.org/gopkg.in/go-playground/validator.v8#Validate.RegisterStructValidation
+- Struct level example - https://github.com/go-playground/validator/blob/v8.18.2/examples/struct-level/struct_level.go
+- Validator release notes - https://github.com/go-playground/validator/releases/tag/v8.7

examples/struct-lvl-validations/server.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"net/http"
+	"reflect"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gin-gonic/gin/binding"
+	validator "gopkg.in/go-playground/validator.v8"
+)
+
+// User contains user information.
+type User struct {
+	FirstName string `json:"fname"`
+	LastName  string `json:"lname"`
+	Email     string `binding:"required,email"`
+}
+
+// UserStructLevelValidation contains custom struct level validations that don't always
+// make sense at the field validation level. For example, this function validates that either
+// FirstName or LastName exist; could have done that with a custom field validation but then
+// would have had to add it to both fields duplicating the logic + overhead, this way it's
+// only validated once.
+//
+// NOTE: you may ask why wouldn't not just do this outside of validator. Doing this way
+// hooks right into validator and you can combine with validation tags and still have a
+// common error output format.
+func UserStructLevelValidation(v *validator.Validate, structLevel *validator.StructLevel) {
+	user := structLevel.CurrentStruct.Interface().(User)
+
+	if len(user.FirstName) == 0 && len(user.LastName) == 0 {
+		structLevel.ReportError(
+			reflect.ValueOf(user.FirstName), "FirstName", "fname", "fnameorlname",
+		)
+		structLevel.ReportError(
+			reflect.ValueOf(user.LastName), "LastName", "lname", "fnameorlname",
+		)
+	}
+
+	// plus can to more, even with different tag than "fnameorlname"
+}
+
+func main() {
+	route := gin.Default()
+
+	if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
+		v.RegisterStructValidation(UserStructLevelValidation, User{})
+	}
+
+	route.POST("/user", validateUser)
+	route.Run(":8085")
+}
+
+func validateUser(c *gin.Context) {
+	var u User
+	if err := c.ShouldBindJSON(&u); err == nil {
+		c.JSON(http.StatusOK, gin.H{"message": "User validation successful."})
+	} else {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"message": "User validation failed!",
+			"error":   err.Error(),
+		})
+	}
+}