Feat: Add support for custom validation error handler in OApiApp configuration (#20)

* Add support for custom validation error handler in OApiApp configuration

* Add example and tests for custom validation error handler

* Add test for custom validation error handler with disabled OpenAPI docs

* Refactor comments and import order in custom validation error example

* Add test to ensure validation is enabled when only custom error handler is set

* Enhance validation logic to ensure validation remains enabled when a ValidationErrorHandler is set without explicit disablement

* Update README to clarify automatic validation enablement with ValidationErrorHandler

* Refactor validation logic to restore defaults when ValidationErrorHandler is set without explicit boolean configurations

* Add test to verify OpenAPI docs are enabled by default with only ValidationErrorHandler configured

Author: moutonjeremy

_examples/custom_validation_error/README.md

@@ -0,0 +1,146 @@
+# Custom Validation Error Handler Example
+
+This example demonstrates how to use a custom validation error handler in fiber-oapi to return your own error structure when validation fails.
+
+## Problem
+
+By default, fiber-oapi returns a standard `ErrorResponse` structure when validation fails:
+
+```json
+{
+  "code": 400,
+  "details": "validation error message",
+  "type": "validation_error"
+}
+```
+
+However, you might want all errors in your API to follow the same structure, including validation errors.
+
+## Solution
+
+Use the `ValidationErrorHandler` field in the `Config` to provide a custom function that handles validation errors:
+
+**Note:** When you configure a `ValidationErrorHandler`, validation is automatically enabled (`EnableValidation: true` by default). You don't need to explicitly set `EnableValidation: true` unless you're also configuring other options.
+
+```go
+// Minimal configuration - validation is automatically enabled
+oapi := fiberoapi.New(app, fiberoapi.Config{
+    ValidationErrorHandler: func(c *fiber.Ctx, err error) error {
+        // Return your custom error structure
+        return c.Status(fiber.StatusBadRequest).JSON(CustomErrorResponse{
+            Success: false,
+            Message: err.Error(),
+            Code:    "VALIDATION_ERROR",
+        })
+    },
+})
+```
+
+```go
+// Or with explicit configuration
+oapi := fiberoapi.New(app, fiberoapi.Config{
+    EnableValidation: true,
+    EnableOpenAPIDocs: true,
+    ValidationErrorHandler: func(c *fiber.Ctx, err error) error {
+        return c.Status(fiber.StatusBadRequest).JSON(CustomErrorResponse{
+            Success: false,
+            Message: err.Error(),
+            Code:    "VALIDATION_ERROR",
+        })
+    },
+})
+```
+
+## Running the Example
+
+```bash
+go run main.go
+```
+
+## Testing
+
+Try sending an invalid request:
+
+```bash
+# Missing required fields
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Response:
+# {
+#   "success": false,
+#   "message": "Key: 'CreateUserInput.Name' Error:Field validation for 'Name' failed on the 'required' tag...",
+#   "code": "VALIDATION_ERROR"
+# }
+```
+
+```bash
+# Invalid email format
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John",
+    "email": "invalid-email",
+    "age": 25
+  }'
+
+# Response:
+# {
+#   "success": false,
+#   "message": "Key: 'CreateUserInput.Email' Error:Field validation for 'Email' failed on the 'email' tag",
+#   "code": "VALIDATION_ERROR"
+# }
+```
+
+```bash
+# Valid request
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Doe",
+    "email": "john@example.com",
+    "age": 25
+  }'
+
+# Response:
+# {
+#   "id": 1,
+#   "name": "John Doe",
+#   "email": "john@example.com",
+#   "age": 25,
+#   "message": "User created successfully"
+# }
+```
+
+## Advanced Usage
+
+You can also parse the validation error to extract detailed information:
+
+```go
+ValidationErrorHandler: func(c *fiber.Ctx, err error) error {
+    // Parse validator errors for more details
+    if validationErrs, ok := err.(validator.ValidationErrors); ok {
+        errors := make([]map[string]string, 0)
+        for _, fieldErr := range validationErrs {
+            errors = append(errors, map[string]string{
+                "field":   fieldErr.Field(),
+                "tag":     fieldErr.Tag(),
+                "value":   fmt.Sprintf("%v", fieldErr.Value()),
+                "message": fieldErr.Error(),
+            })
+        }
+        return c.Status(fiber.StatusBadRequest).JSON(map[string]interface{}{
+            "success": false,
+            "errors":  errors,
+        })
+    }
+
+    // Fallback for other errors
+    return c.Status(fiber.StatusBadRequest).JSON(CustomErrorResponse{
+        Success: false,
+        Message: err.Error(),
+        Code:    "VALIDATION_ERROR",
+    })
+},
+```

_examples/custom_validation_error/go.mod

@@ -0,0 +1,31 @@
+module custom_validation_error_example
+
+go 1.25.1
+
+replace github.com/labbs/fiber-oapi => ../..
+
+require (
+	github.com/gofiber/fiber/v2 v2.52.10
+	github.com/labbs/fiber-oapi v0.0.0-00010101000000-000000000000
+)
+
+require (
+	github.com/andybalholm/brotli v1.2.0 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.10 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.28.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-runewidth v0.0.17 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/fasthttp v1.66.0 // indirect
+	golang.org/x/crypto v0.45.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

_examples/custom_validation_error/go.sum

@@ -0,0 +1,52 @@
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/gabriel-vasile/mimetype v1.4.10 h1:zyueNbySn/z8mJZHLt6IPw0KoZsiQNszIpU+bX4+ZK0=
+github.com/gabriel-vasile/mimetype v1.4.10/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.28.0 h1:Q7ibns33JjyW48gHkuFT91qX48KG0ktULL6FgHdG688=
+github.com/go-playground/validator/v10 v10.28.0/go.mod h1:GoI6I1SjPBh9p7ykNE/yj3fFYbyDOpwMn5KXd+m2hUU=
+github.com/gofiber/fiber/v2 v2.52.10 h1:jRHROi2BuNti6NYXmZ6gbNSfT3zj/8c0xy94GOU5elY=
+github.com/gofiber/fiber/v2 v2.52.10/go.mod h1:YEcBbO/FB+5M1IZNBP9FO3J9281zgPAreiI1oqg8nDw=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-runewidth v0.0.17 h1:78v8ZlW0bP43XfmAfPsdXcoNCelfMHsDmd/pkENfrjQ=
+github.com/mattn/go-runewidth v0.0.17/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
+github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
+github.com/valyala/fasthttp v1.66.0 h1:M87A0Z7EayeyNaV6pfO3tUTUiYO0dZfEJnRGXTVNuyU=
+github.com/valyala/fasthttp v1.66.0/go.mod h1:Y4eC+zwoocmXSVCB1JmhNbYtS7tZPRI2ztPB72EVObs=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
+golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
+golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
+golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

_examples/custom_validation_error/main.go

@@ -0,0 +1,76 @@
+package main
+
+import (
+	"log"
+
+	"github.com/gofiber/fiber/v2"
+	fiberoapi "github.com/labbs/fiber-oapi"
+)
+
+// CustomErrorResponse is the structure for custom validation error responses
+type CustomErrorResponse struct {
+	Success bool   `json:"success"`
+	Message string `json:"message"`
+	Code    string `json:"code"`
+}
+
+// CreateUserInput is the input structure for creating a user
+type CreateUserInput struct {
+	Name  string `json:"name" validate:"required,min=3"`
+	Email string `json:"email" validate:"required,email"`
+	Age   int    `json:"age" validate:"required,min=18,max=100"`
+}
+
+// CreateUserOutput is the output structure for creating a user
+type CreateUserOutput struct {
+	ID      int    `json:"id"`
+	Name    string `json:"name"`
+	Email   string `json:"email"`
+	Age     int    `json:"age"`
+	Message string `json:"message"`
+}
+
+func main() {
+	app := fiber.New()
+
+	// Configure fiber-oapi with a custom validation error handler
+	oapi := fiberoapi.New(app, fiberoapi.Config{
+		EnableValidation:  true,
+		EnableOpenAPIDocs: true,
+		// Define your custom handler for validation errors
+		ValidationErrorHandler: func(c *fiber.Ctx, err error) error {
+			// You can parse the validation error to extract more details
+			// or simply return your custom structure
+			return c.Status(fiber.StatusBadRequest).JSON(CustomErrorResponse{
+				Success: false,
+				Message: err.Error(),
+				Code:    "VALIDATION_ERROR",
+			})
+		},
+	})
+
+	// Define your endpoint
+	fiberoapi.Post[CreateUserInput, CreateUserOutput, struct{}](
+		oapi,
+		"/users",
+		func(c *fiber.Ctx, input CreateUserInput) (CreateUserOutput, struct{}) {
+			// User creation logic goes here
+			return CreateUserOutput{
+				ID:      1,
+				Name:    input.Name,
+				Email:   input.Email,
+				Age:     input.Age,
+				Message: "User created successfully",
+			}, struct{}{}
+		},
+		fiberoapi.OpenAPIOptions{
+			Summary:     "Create a new user",
+			Description: "Creates a new user with validation",
+			Tags:        []string{"users"},
+		},
+	)
+
+	log.Println("Server starting on :3000")
+	log.Println("OpenAPI docs available at http://localhost:3000/docs")
+	log.Fatal(oapi.Listen(":3000"))
+}