feat: support example method to enhance openapi reporter

Author: LeadcodeDev

benchmark/array_object.dart

@@ -24,5 +24,6 @@ void main() {
     iterationCount++;
   }
 
-  print('Array Object : Processed $iterationCount iterations in ${duration.inSeconds} seconds');
+  print(
+      'Array Object : Processed $iterationCount iterations in ${duration.inSeconds} seconds');
 }

lib/src/contracts/schema.dart

@@ -2,7 +2,8 @@ import 'package:vine/src/contracts/vine.dart';
 import 'package:vine/src/introspection.dart';
 import 'package:vine/src/schema/object/object_schema.dart';
 
-abstract interface class VineSchema<T extends ErrorReporter> implements SchemaIntrospection {
+abstract interface class VineSchema<T extends ErrorReporter>
+    implements SchemaIntrospection {
   /// Validate the field [field] the field to validate
   void parse(VineValidationContext ctx, FieldContext field);
 
@@ -63,7 +64,8 @@ abstract interface class BasicSchema<T extends VineSchema> {
   T optional();
 }
 
-abstract interface class VineString implements VineSchema, BasicSchema<VineString> {
+abstract interface class VineString
+    implements VineSchema, BasicSchema<VineString> {
   /// Check if the string has a minimum length [value] the minimum length [message] the error message to display
   /// ```dart
   /// vine.string().minLength(5);
@@ -203,7 +205,8 @@ abstract interface class VineString implements VineSchema, BasicSchema<VineStrin
   /// vine.string().confirmed(
   ///   message: 'The value must be confirmed');
   /// ```
-  VineString confirmed({String? property, bool include = false, String? message});
+  VineString confirmed(
+      {String? property, bool include = false, String? message});
 
   /// Remove leading and trailing whitespace from the string
   /// ```dart
@@ -321,9 +324,16 @@ abstract interface class VineString implements VineSchema, BasicSchema<VineStrin
   ///   message: 'The value must contain only alphabetic characters');
   /// ```
   VineString regex(RegExp expression, {String? message});
+
+  /// Set the example value for the string [value] the example value
+  /// ```dart
+  /// vine.string().example('foo');
+  /// ```
+  VineString example(String value);
 }
 
-abstract interface class VineNumber implements VineSchema, BasicSchema<VineNumber> {
+abstract interface class VineNumber
+    implements VineSchema, BasicSchema<VineNumber> {
   /// Check if the number is in a range of values [values] the range of values [message] the error message to display
   /// ```dart
   /// vine.number().range([1, 10]);
@@ -392,15 +402,42 @@ abstract interface class VineNumber implements VineSchema, BasicSchema<VineNumbe
   /// You can specify a custom error message
   /// ```dart
   VineNumber integer({String? message});
+
+  /// Set the example value for the number [value] the example value
+  /// ```dart
+  /// vine.number().example(10);
+  /// ```
+  VineNumber example(num value);
 }
 
-abstract interface class VineBoolean implements VineSchema, BasicSchema<VineBoolean> {}
+abstract interface class VineBoolean
+    implements VineSchema, BasicSchema<VineBoolean> {
+  /// Set the example value for the boolean [value] the example value
+  /// ```dart
+  /// vine.boolean().example(true);
+  /// ```
+  VineBoolean example(bool value);
+}
 
-abstract interface class VineAny implements VineSchema, BasicSchema<VineAny> {}
+abstract interface class VineAny implements VineSchema, BasicSchema<VineAny> {
+  /// Set the example value for the any [value] the example value
+  /// ```dart
+  /// vine.any().example('foo');
+  /// ```
+  VineAny example(dynamic value);
+}
 
-abstract interface class VineEnum implements VineSchema, BasicSchema<VineEnum> {}
+abstract interface class VineEnum<T extends VineEnumerable>
+    implements VineSchema, BasicSchema<VineEnum<T>> {
+  /// Set the example value for the enum [value] the example value
+  /// ```dart
+  /// vine.enum().example('foo');
+  /// ```
+  VineEnum<T> example(T value);
+}
 
-abstract interface class VineObject implements VineSchema, BasicSchema<VineObject> {
+abstract interface class VineObject
+    implements VineSchema, BasicSchema<VineObject> {
   Map<String, VineSchema> get properties;
 
   VineObject merge(VineObjectSchema schema);
@@ -415,7 +452,8 @@ abstract interface class VineGroup implements VineSchema {
   ///     'email': vine.string().required().email(),
   ///   });
   /// });
-  VineGroup when(bool Function(Map<String, dynamic> data) fn, Map<String, VineSchema> object);
+  VineGroup when(bool Function(Map<String, dynamic> data) fn,
+      Map<String, VineSchema> object);
 
   /// Apply the schema if the condition is not met [fn] the schema to apply
   /// ```dart
@@ -432,7 +470,8 @@ abstract interface class VineGroup implements VineSchema {
   VineGroup otherwise(Function(VineValidationContext, FieldContext) fn);
 }
 
-abstract interface class VineArray implements VineSchema, BasicSchema<VineArray> {
+abstract interface class VineArray
+    implements VineSchema, BasicSchema<VineArray> {
   /// Check if the array has a minimum length [value] the minimum length [message] the error message to display
   /// ```dart
   /// vine.array().minLength(5);
@@ -474,7 +513,10 @@ abstract interface class VineArray implements VineSchema, BasicSchema<VineArray>
   VineArray unique({String? message});
 }
 
-abstract interface class VineUnion implements VineSchema, BasicSchema<VineUnion> {}
+abstract interface class VineUnion
+    implements VineSchema, BasicSchema<VineUnion> {
+  VineUnion example(dynamic value);
+}
 
 abstract interface class VineDate implements VineSchema, BasicSchema<VineDate> {
   /// Check if the date is before [value] the date to compare [message] the error message to display
@@ -539,4 +581,10 @@ abstract interface class VineDate implements VineSchema, BasicSchema<VineDate> {
   ///   message: 'The date must be between the start and end date');
   /// ```
   VineDate betweenFields(String start, String end, {String? message});
+
+  /// Set the example value for the date [value] the example value
+  /// ```dart
+  /// vine.date().example(DateTime.now());
+  /// ```
+  VineDate example(String value);
 }

lib/src/schema/any_schema.dart

@@ -6,6 +6,8 @@ import 'package:vine/src/rule_parser.dart';
 import 'package:vine/src/rules/basic_rule.dart';
 
 final class VineAnySchema extends RuleParser implements VineAny {
+  dynamic _example;
+
   VineAnySchema(super._rules);
 
   @override
@@ -50,6 +52,12 @@ final class VineAnySchema extends RuleParser implements VineAny {
     return this;
   }
 
+  @override
+  VineAny example(dynamic value) {
+    _example = value;
+    return this;
+  }
+
   @override
   VineAny clone() {
     return VineAnySchema(Queue.of(rules));
@@ -59,6 +67,7 @@ final class VineAnySchema extends RuleParser implements VineAny {
   Map<String, dynamic> introspect({String? name}) {
     return {
       'required': !isOptional,
+      if (_example != null) 'example': _example,
     };
   }
 }

lib/src/schema/boolean_schema.dart

@@ -6,6 +6,8 @@ import 'package:vine/src/rule_parser.dart';
 import 'package:vine/src/rules/basic_rule.dart';
 
 final class VineBooleanSchema extends RuleParser implements VineBoolean {
+  dynamic _example;
+
   VineBooleanSchema(super._rules);
 
   @override
@@ -50,6 +52,12 @@ final class VineBooleanSchema extends RuleParser implements VineBoolean {
     return this;
   }
 
+  @override
+  VineBoolean example(bool value) {
+    _example = value;
+    return this;
+  }
+
   @override
   VineBoolean clone() {
     return VineBooleanSchema(Queue.of(rules));
@@ -60,7 +68,7 @@ final class VineBooleanSchema extends RuleParser implements VineBoolean {
     return {
       'type': 'boolean',
       'required': !isOptional,
-      'example': true,
+      'example': _example ?? true,
     };
   }
 }

lib/src/schema/date_schema.dart

@@ -7,6 +7,8 @@ import 'package:vine/src/rules/basic_rule.dart';
 import 'package:vine/src/rules/date_rule.dart';
 
 final class VineDateSchema extends RuleParser implements VineDate {
+  dynamic _example;
+
   VineDateSchema(super._rules);
 
   @override
@@ -87,6 +89,12 @@ final class VineDateSchema extends RuleParser implements VineDate {
     return this;
   }
 
+  @override
+  VineDate example(String value) {
+    _example = value;
+    return this;
+  }
+
   @override
   VineDate clone() {
     return VineDateSchema(Queue.of(rules));
@@ -98,7 +106,7 @@ final class VineDateSchema extends RuleParser implements VineDate {
       'type': 'string',
       'format': 'date-time',
       'required': !isOptional,
-      'example': DateTime.now().toIso8601String(),
+      if (_example != null) 'example': _example,
     };
   }
 }

lib/src/schema/enum_schema.dart

@@ -3,64 +3,72 @@ import 'dart:collection';
 import 'package:vine/vine.dart';
 
 final class VineEnumSchema<T extends VineEnumerable> extends RuleParser
-    implements VineEnum {
+    implements VineEnum<T> {
   final List<T> _source;
+  T? _example;
+
   VineEnumSchema(super._rules, this._source);
 
   @override
-  VineEnum requiredIfExist(List<String> values) {
+  VineEnum<T> requiredIfExist(List<String> values) {
     super.addRule(VineRequiredIfExistRule(values), positioned: true);
     return this;
   }
 
   @override
-  VineEnum requiredIfAnyExist(List<String> values) {
+  VineEnum<T> requiredIfAnyExist(List<String> values) {
     super.addRule(VineRequiredIfAnyExistRule(values), positioned: true);
     return this;
   }
 
   @override
-  VineEnum requiredIfMissing(List<String> values) {
+  VineEnum<T> requiredIfMissing(List<String> values) {
     super.addRule(VineRequiredIfMissingRule(values), positioned: true);
     return this;
   }
 
   @override
-  VineEnum requiredIfAnyMissing(List<String> values) {
+  VineEnum<T> requiredIfAnyMissing(List<String> values) {
     super.addRule(VineRequiredIfAnyMissingRule(values), positioned: true);
     return this;
   }
 
   @override
-  VineEnum transform(Function(VineValidationContext, FieldContext) fn) {
+  VineEnum<T> transform(Function(VineValidationContext, FieldContext) fn) {
     super.addRule(VineTransformRule(fn));
     return this;
   }
 
   @override
-  VineEnum nullable() {
+  VineEnum<T> nullable() {
     super.isNullable = true;
     return this;
   }
 
   @override
-  VineEnum optional() {
+  VineEnum<T> optional() {
     super.isOptional = true;
     return this;
   }
 
   @override
-  VineEnum clone() {
+  VineEnum<T> example(T value) {
+    _example = value;
+    return this;
+  }
+
+  @override
+  VineEnum<T> clone() {
     return VineEnumSchema(Queue.of(rules), _source.toList());
   }
 
   @override
   Map<String, dynamic> introspect({String? name}) {
     return {
-      'type': 'string', // Adapt selon le type des valeurs
+      'type': 'string',
       'enum': _source.map((e) => e.value).toList(),
       'required': !isOptional,
-      'example': _source.firstOrNull?.value,
+      'example': _example?.value ?? _source.first.value,
     };
   }
 }

lib/src/schema/number_schema.dart

@@ -7,6 +7,8 @@ import 'package:vine/src/rules/basic_rule.dart';
 import 'package:vine/src/rules/number_rule.dart';
 
 final class VineNumberSchema extends RuleParser implements VineNumber {
+  dynamic _example;
+
   VineNumberSchema(super._rules);
 
   @override
@@ -93,6 +95,12 @@ final class VineNumberSchema extends RuleParser implements VineNumber {
     return this;
   }
 
+  @override
+  VineNumber example(num value) {
+    _example = value;
+    return this;
+  }
+
   @override
   VineNumber clone() {
     return VineNumberSchema(Queue.of(rules));
@@ -134,10 +142,15 @@ final class VineNumberSchema extends RuleParser implements VineNumber {
     }
 
     // Détermination du type
-    final type = isInteger ? 'integer' : isDouble ? 'number' : 'number';
+    final type = isInteger
+        ? 'integer'
+        : isDouble
+            ? 'number'
+            : 'number';
 
     // Validation de l'exemple
-    if (validations.containsKey('minimum') || validations.containsKey('maximum')) {
+    if (validations.containsKey('minimum') ||
+        validations.containsKey('maximum')) {
       example = example.clamp(
         validations['minimum'] ?? '-Infinity',
         validations['maximum'] ?? 'Infinity',
@@ -150,7 +163,7 @@ final class VineNumberSchema extends RuleParser implements VineNumber {
       'type': type,
       'required': !isOptional,
       if (enums != null) 'enum': enums,
-      'example': example,
+      'example': _example ?? example,
       ...validations,
     }..removeWhere((_, v) => v == null);
   }

lib/src/schema/object/object_schema.dart

@@ -81,7 +81,10 @@ final class VineObjectSchema extends RuleParser implements VineObject {
         schema.remove('required');
       }
 
-      example[entry.key] = schema['example'] ?? (schema['examples'] as List).firstOrNull;
+      example[entry.key] = schema['example'] ??
+          (schema['examples'] is List
+              ? (schema['examples'] as List).firstOrNull
+              : null);
     }
 
     return {