feat: implement open api reporter

LeadcodeDev · LeadcodeDev · commit d9bca6a6ef40 · 2025-02-26T21:19:41.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.2.0
+- Move rules from handlers to dedicated classes
+- Implement OpenAPI reporter
+
 ## 1.1.0
 - Implement `VineBasics` validation rules
 - Implement `VineGroup` validation rules
diff --git a/README.md b/README.md
@@ -21,13 +21,13 @@ ensuring that data complies with an expected format before it is used, which red
 | 🚧 Null Safety            | Full support for nullable and optional fields                |
 | ⚙️ Composable             | Compiled and reusable schemas                                |
 | ⚡ Fast Performance        | ~ 29 000 000 ops/s                                           |
-| 📦 Extremely small size   | Package size `< 20kb`                                        |
+| 📦 Extremely small size   | Package size `< 21kb`                                        |
+| 🚀 OpenApi reporter       | Export your schemas as OpenApi spec                          |
 
 ## 🚀 Usage
 
 Vine is a data structure validation library for Dart. You may use it to validate the HTTP request body or any data in
-your
-backend applications.
+your backend applications.
 
 ### Built for validating form data and JSON payloads
 
@@ -57,13 +57,13 @@ import 'package:vine/vine.dart';
 
 void main() {
   final validator = vine.compile(
-      vine.object({
-        'username': vine.string().minLength(3).maxLength(20),
-        'email': vine.string().email(),
-        'age': vine.number().min(18).optional(),
-        'isAdmin': vine.boolean(),
-        'features': vine.array(vine.string()),
-      }));
+    vine.object({
+      'username': vine.string().minLength(3).maxLength(20),
+      'email': vine.string().email(),
+      'age': vine.number().min(18).optional(),
+      'isAdmin': vine.boolean(),
+      'features': vine.array(vine.string()),
+    }));
 
   try {
     final payload = {
@@ -82,6 +82,29 @@ void main() {
 }
 ```
 
+### OpenAPI reporter
+
+Vine can generate an OpenAPI schema from your validation schemas. 
+This feature is useful when you want to document your API
+
+```dart
+final schema = vine.object({
+  'stringField': vine.string().minLength(3).maxLength(20),
+  'emailField': vine.string().email(),
+  'numberField': vine.number().min(18).max(100),
+  'booleanField': vine.boolean(),
+  'enumField': vine.enumerate(MyEnum.values),
+  'arrayField': vine.array(vine.string().minLength(3).maxLength(20)).minLength(1),
+  'unionField': vine.union([
+    vine.string().minLength(3).maxLength(20),
+    vine.number().min(10).max(20),
+  ]),
+});
+
+final reporter = vine.openApi.report(schemas: {'MySchema': schema});
+print(reporter);
+```
+
 ## ❤️ Credit
 
 I would like to thank [Harminder Virk](https://github.com/thetutlage) for all his open-source work on Adonis.js and for
diff --git a/lib/src/contracts/schema.dart b/lib/src/contracts/schema.dart
@@ -1,7 +1,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> {
+abstract interface class VineSchema<T extends ErrorReporter> implements SchemaIntrospection {
   /// Validate the field [field] the field to validate
   void parse(VineValidationContext ctx, FieldContext field);
 
diff --git a/lib/src/introspection.dart b/lib/src/introspection.dart
@@ -0,0 +1,21 @@
+import 'package:vine/src/contracts/schema.dart';
+
+abstract interface class SchemaIntrospection {
+  Map<String, dynamic> introspect({String? name});
+}
+
+final class OpenApiReporter {
+  Map<String, dynamic> report(
+      {required Map<String, VineSchema> schemas, String version = '3.1.0'}) {
+    final components = <String, dynamic>{};
+
+    for (final entry in schemas.entries) {
+      components[entry.key] = entry.value.introspect(name: entry.key);
+    }
+
+    return {
+      'openapi': version,
+      'components': {'schemas': components},
+    };
+  }
+}
diff --git a/lib/src/schema/any_schema.dart b/lib/src/schema/any_schema.dart
@@ -54,4 +54,11 @@ final class VineAnySchema extends RuleParser implements VineAny {
   VineAny clone() {
     return VineAnySchema(Queue.of(rules));
   }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    return {
+      'required': !isOptional,
+    };
+  }
 }
diff --git a/lib/src/schema/array_schema.dart b/lib/src/schema/array_schema.dart
@@ -1,5 +1,6 @@
 import 'dart:collection';
 
+import 'package:vine/src/contracts/rule.dart';
 import 'package:vine/src/contracts/schema.dart';
 import 'package:vine/src/contracts/vine.dart';
 import 'package:vine/src/rule_parser.dart';
@@ -79,4 +80,35 @@ final class VineArraySchema extends RuleParser implements VineArray {
   VineArray clone() {
     return VineArraySchema(Queue.of(rules));
   }
+
+  int? _getRuleValue<T extends VineRule>() {
+    return switch (rules.whereType<T>().firstOrNull) {
+      VineArrayMinLengthRule rule => rule.minValue,
+      VineArrayFixedLengthRule rule => rule.count,
+      _ => null,
+    };
+  }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    final itemsSchema = rules.whereType<VineArrayRule>().firstOrNull?.schema.introspect();
+    itemsSchema?.remove('required');
+    final example = itemsSchema?['example'];
+    itemsSchema?.remove('example');
+
+
+    final minValue = _getRuleValue<VineArrayMinLengthRule>();
+    final maxValue = _getRuleValue<VineArrayMaxLengthRule>();
+    final isUnique = rules.whereType<VineArrayUniqueRule>().isNotEmpty;
+
+    return {
+      'type': 'array',
+      'items': itemsSchema ?? {'type': 'any'},
+      if (minValue != null) 'minItems': minValue,
+      if (maxValue != null) 'maxItems': maxValue,
+      if (isUnique) 'uniqueItems': isUnique,
+      'required': !isOptional,
+      'example': [example],
+    };
+  }
 }
diff --git a/lib/src/schema/boolean_schema.dart b/lib/src/schema/boolean_schema.dart
@@ -54,4 +54,13 @@ final class VineBooleanSchema extends RuleParser implements VineBoolean {
   VineBoolean clone() {
     return VineBooleanSchema(Queue.of(rules));
   }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    return {
+      'type': 'boolean',
+      'required': !isOptional,
+      'example': true,
+    };
+  }
 }
diff --git a/lib/src/schema/date_schema.dart b/lib/src/schema/date_schema.dart
@@ -91,4 +91,14 @@ final class VineDateSchema extends RuleParser implements VineDate {
   VineDate clone() {
     return VineDateSchema(Queue.of(rules));
   }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    return {
+      'type': 'string',
+      'format': 'date-time',
+      'required': !isOptional,
+      'example': DateTime.now().toIso8601String(),
+    };
+  }
 }
diff --git a/lib/src/schema/enum_schema.dart b/lib/src/schema/enum_schema.dart
@@ -5,8 +5,9 @@ import 'package:vine/src/rule_parser.dart';
 import 'package:vine/src/rules/basic_rule.dart';
 import 'package:vine/vine.dart';
 
-final class VineEnumSchema extends RuleParser implements VineEnum {
-  VineEnumSchema(super._rules);
+final class VineEnumSchema<T extends VineEnumerable> extends RuleParser implements VineEnum {
+  final List<T> _source;
+  VineEnumSchema(super._rules, this._source);
 
   @override
   VineEnum requiredIfExist(List<String> values) {
@@ -52,6 +53,16 @@ final class VineEnumSchema extends RuleParser implements VineEnum {
 
   @override
   VineEnum clone() {
-    return VineEnumSchema(Queue.of(rules));
+    return VineEnumSchema(Queue.of(rules), _source.toList());
+  }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    return {
+      'type': 'string', // Adapt selon le type des valeurs
+      'enum': _source.map((e) => e.value).toList(),
+      'required': !isOptional,
+      'example': _source.firstOrNull?.value,
+    };
   }
 }
diff --git a/lib/src/schema/number_schema.dart b/lib/src/schema/number_schema.dart
@@ -97,4 +97,61 @@ final class VineNumberSchema extends RuleParser implements VineNumber {
   VineNumber clone() {
     return VineNumberSchema(Queue.of(rules));
   }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    final validations = <String, dynamic>{};
+    bool isInteger = false;
+    bool isDouble = false;
+    List<num>? enums;
+    num example = 0;
+
+    // Analyse des règles
+    for (final rule in rules) {
+      switch (rule) {
+        case VineIntegerRule():
+          isInteger = true;
+          example = 42;
+        case VineDoubleRule():
+          isDouble = true;
+          example = 3.14;
+        case VineMinRule(:final minValue):
+          validations['minimum'] = minValue;
+          example = minValue + (isInteger ? 1 : 0.5);
+        case VineMaxRule(:final maxValue):
+          validations['maximum'] = maxValue;
+          example = maxValue - (isInteger ? 1 : 0.5);
+        case VineRangeRule(:final values):
+          enums = values;
+          example = values.firstOrNull ?? example;
+        case VinePositiveRule():
+          validations['exclusiveMinimum'] = 0;
+          example = 1;
+        case VineNegativeRule():
+          validations['exclusiveMaximum'] = 0;
+          example = -1;
+      }
+    }
+
+    // Détermination du type
+    final type = isInteger ? 'integer' : isDouble ? 'number' : 'number';
+
+    // Validation de l'exemple
+    if (validations.containsKey('minimum') || validations.containsKey('maximum')) {
+      example = example.clamp(
+        validations['minimum'] ?? '-Infinity',
+        validations['maximum'] ?? 'Infinity',
+      );
+    }
+
+    // Construction du schéma
+    return {
+      if (name != null) 'title': name,
+      'type': type,
+      'required': !isOptional,
+      if (enums != null) 'enum': enums,
+      'example': example,
+      ...validations,
+    }..removeWhere((_, v) => v == null);
+  }
 }
diff --git a/lib/src/schema/object/group_schema.dart b/lib/src/schema/object/group_schema.dart
@@ -22,4 +22,9 @@ final class VineGroupSchema extends RuleParser implements VineGroup {
   VineGroup clone() {
     return VineGroupSchema(Queue.of(rules));
   }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    return {};
+  }
 }
diff --git a/lib/src/schema/object/object_schema.dart b/lib/src/schema/object/object_schema.dart
@@ -65,4 +65,32 @@ final class VineObjectSchema extends RuleParser implements VineObject {
   VineObject clone() {
     return VineObjectSchema({..._properties}, Queue.of(rules));
   }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    final Map<String, dynamic> properties = {};
+    final List<String> requiredFields = [];
+    final Map<String, dynamic> example = {};
+
+    for (final entry in _properties.entries) {
+      final schema = entry.value.introspect();
+      properties[entry.key] = schema;
+
+      if (schema['required'] ?? false) {
+        requiredFields.add(entry.key);
+        schema.remove('required');
+      }
+
+      example[entry.key] = schema['example'] ?? (schema['examples'] as List).firstOrNull;
+    }
+
+    return {
+      if (name != null) 'title': name,
+      'type': 'object',
+      'properties': properties,
+      if (requiredFields.isNotEmpty) 'required': requiredFields,
+      'additionalProperties': false,
+      'example': example,
+    };
+  }
 }
diff --git a/lib/src/schema/string_schema.dart b/lib/src/schema/string_schema.dart
@@ -1,9 +1,5 @@
 import 'dart:collection';
 
-import 'package:vine/src/contracts/schema.dart';
-import 'package:vine/src/rule_parser.dart';
-import 'package:vine/src/rules/basic_rule.dart';
-import 'package:vine/src/rules/string_rule.dart';
 import 'package:vine/vine.dart';
 
 final class VineStringSchema extends RuleParser implements VineString {
@@ -197,4 +193,44 @@ final class VineStringSchema extends RuleParser implements VineString {
   VineString clone() {
     return VineStringSchema(Queue.of(rules));
   }
+
+  @override
+  Map<String, dynamic> introspect({String? name}) {
+    final validations = <String, dynamic>{};
+    String? format;
+    String example = 'foo';
+    List<String>? enums;
+
+    for (final rule in rules) {
+      if (rule is VineEmailRule) {
+        format = 'email';
+        example = 'user@example.com';
+        continue;
+      }
+
+      if (rule is VineUuidRule) {
+        format = 'uuid';
+        example = '550e8400-e29b-41d4-a716-446655440000';
+        continue;
+      }
+
+      if (rule is VineMinLengthRule) {
+        validations['minLength'] = rule.minValue;
+        continue;
+      }
+
+      if (rule is VineEnumRule) {
+        enums = rule.source.map((e) => e.value.toString()).toList();
+      }
+    }
+
+    return {
+      'type': 'string',
+      'format': format,
+      'required': !isOptional,
+      'example': example,
+      'enum': enums,
+      ...validations,
+    }..removeWhere((_, v) => v == null);
+  }
 }
diff --git a/lib/src/schema/union_schema.dart b/lib/src/schema/union_schema.dart
diff --git a/lib/src/vine.dart b/lib/src/vine.dart
diff --git a/pubspec.yaml b/pubspec.yaml
diff --git a/test/open_api_test.dart b/test/open_api_test.dart
diff --git a/test/vine_test.dart b/test/vine_test.dart

Original file line number	Diff line number	Diff line change
`@@ -54,4 +54,11 @@ final class VineAnySchema extends RuleParser implements VineAny {`
`54`	`54`	`VineAny clone() {`
`55`	`55`	`return VineAnySchema(Queue.of(rules));`
`56`	`56`	`}`
	`57`	`+`
	`58`	`+ @override`
	`59`	`+ Map<String, dynamic> introspect({String? name}) {`
	`60`	`+ return {`
	`61`	`+ 'required': !isOptional,`
	`62`	`+ };`
	`63`	`+ }`
`57`	`64`	`}`
Original file line number	Diff line number	Diff line change
`@@ -54,4 +54,13 @@ final class VineBooleanSchema extends RuleParser implements VineBoolean {`
`54`	`54`	`VineBoolean clone() {`
`55`	`55`	`return VineBooleanSchema(Queue.of(rules));`
`56`	`56`	`}`
	`57`	`+`
	`58`	`+ @override`
	`59`	`+ Map<String, dynamic> introspect({String? name}) {`
	`60`	`+ return {`
	`61`	`+ 'type': 'boolean',`
	`62`	`+ 'required': !isOptional,`
	`63`	`+ 'example': true,`
	`64`	`+ };`
	`65`	`+ }`
`57`	`66`	`}`