synthra 0.1.0

data/lib/synthra/export/openapi.rb

@@ -0,0 +1,514 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module Synthra
+  module Export
+    # OpenAPI/Swagger Export
+    #
+    # Generates OpenAPI 3.0 specifications from Synthra schemas.
+    # Includes complete API definitions with endpoints for data generation.
+    #
+    # @example Generate OpenAPI spec
+    #   exporter = Synthra::Export::OpenAPI.new(registry)
+    #   spec = exporter.export
+    #
+    # @example CLI usage
+    #   $ synthra export --all -d schemas -f openapi -o api.yaml
+    #
+    class OpenAPI
+      # Type mapping from Synthra to OpenAPI
+      TYPE_MAP = {
+        # Strings
+        "text" => { "type" => "string" },
+        "name" => { "type" => "string" },
+        "email" => { "type" => "string", "format" => "email" },
+        "url" => { "type" => "string", "format" => "uri" },
+        "uuid" => { "type" => "string", "format" => "uuid" },
+        "date" => { "type" => "string", "format" => "date" },
+        "date_between" => { "type" => "string", "format" => "date" },
+        "past_date" => { "type" => "string", "format" => "date" },
+        "future_date" => { "type" => "string", "format" => "date" },
+        "mobile_device_release_date" => { "type" => "string", "format" => "date" },
+        "now" => { "type" => "string", "format" => "date" },
+        "timestamp" => { "type" => "string", "format" => "date-time" },
+        "datetime" => { "type" => "string", "format" => "date-time" },
+        "phone" => { "type" => "string" },
+        "password" => { "type" => "string", "format" => "password" },
+        "ip" => { "type" => "string", "format" => "ipv4" },
+        "ipv6" => { "type" => "string", "format" => "ipv6" },
+
+        # Numbers (integers)
+        "number" => { "type" => "integer", "format" => "int64" },
+        "integer" => { "type" => "integer", "format" => "int64" },
+        "age" => { "type" => "integer" },
+        "airport_elevation" => { "type" => "integer" },
+        "discount" => { "type" => "integer" },
+        "formula" => { "type" => "integer" },
+        "row_number" => { "type" => "integer" },
+        "sequence" => { "type" => "integer" },
+        "id_sequence" => { "type" => "integer" },
+
+        # Numbers (floats)
+        "float" => { "type" => "number", "format" => "double" },
+        "money" => { "type" => "number", "format" => "double" },
+        "decimal" => { "type" => "number" },
+        "latitude" => { "type" => "number", "format" => "double" },
+        "longitude" => { "type" => "number", "format" => "double" },
+        "airport_latitude" => { "type" => "number", "format" => "double" },
+        "airport_longitude" => { "type" => "number", "format" => "double" },
+        "product_price" => { "type" => "number", "format" => "double" },
+        "tax_rate" => { "type" => "number", "format" => "double" },
+        "transaction_amount" => { "type" => "number", "format" => "double" },
+
+        # Boolean
+        "boolean" => { "type" => "boolean" },
+
+        # Structural
+        "object" => { "type" => "object" },
+        "map_by_field" => { "type" => "object" },
+        "array" => { "type" => "array" },
+        "json_array" => { "type" => "array" },
+
+        # Binary
+        "binary" => { "type" => "string", "format" => "binary" },
+        "base64" => { "type" => "string", "format" => "byte" }
+      }.freeze
+
+      attr_reader :registry, :options
+
+      # Create a new OpenAPI exporter
+      #
+      # @param registry [Registry] schema registry
+      # @param options [Hash] export options
+      # @option options [String] :title API title
+      # @option options [String] :version API version
+      # @option options [String] :description API description
+      # @option options [String] :server_url Base server URL
+      # @option options [Symbol] :format Output format (:yaml or :json)
+      #
+      def initialize(registry, **options)
+        @registry = registry
+        @options = {
+          title: "Synthra Data Generation API",
+          version: "1.0.0",
+          description: "API for generating fake data from schemas",
+          server_url: "http://localhost:3000",
+          format: :yaml
+        }.merge(options)
+      end
+
+      # Export registry to OpenAPI specification
+      #
+      # @return [String] OpenAPI spec in YAML or JSON format
+      #
+      def export
+        spec = build_spec
+        
+        case @options[:format]
+        when :json
+          JSON.pretty_generate(spec)
+        else
+          spec.to_yaml
+        end
+      end
+
+      # Export to specific format
+      #
+      # @param format [Symbol] :yaml or :json
+      # @return [String] formatted spec
+      #
+      def export_as(format)
+        spec = build_spec
+        format == :json ? JSON.pretty_generate(spec) : spec.to_yaml
+      end
+
+      private
+
+      def build_spec
+        {
+          "openapi" => "3.0.3",
+          "info" => build_info,
+          "servers" => build_servers,
+          "tags" => build_tags,
+          "paths" => build_paths,
+          "components" => build_components
+        }
+      end
+
+      def build_info
+        {
+          "title" => @options[:title],
+          "version" => @options[:version],
+          "description" => @options[:description],
+          "contact" => {
+            "name" => "Synthra",
+            "url" => "https://github.com/talaatmagdyx/synthra"
+          }
+        }
+      end
+
+      def build_servers
+        [
+          {
+            "url" => @options[:server_url],
+            "description" => "Data Generation Server"
+          }
+        ]
+      end
+
+      def build_tags
+        @registry.names.sort.map do |name|
+          {
+            "name" => name,
+            "description" => "Operations for #{name} schema"
+          }
+        end
+      end
+
+      def build_paths
+        paths = {}
+        
+        # Schema listing endpoint
+        paths["/api/schemas"] = {
+          "get" => {
+            "tags" => ["Schemas"],
+            "summary" => "List all available schemas",
+            "operationId" => "listSchemas",
+            "responses" => {
+              "200" => {
+                "description" => "List of schema names",
+                "content" => {
+                  "application/json" => {
+                    "schema" => {
+                      "type" => "object",
+                      "properties" => {
+                        "schemas" => {
+                          "type" => "array",
+                          "items" => { "type" => "string" }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        
+        # Per-schema endpoints
+        @registry.names.sort.each do |name|
+          snake_name = to_snake_case(name)
+          
+          # Generate single
+          paths["/api/#{snake_name}"] = {
+            "get" => {
+              "tags" => [name],
+              "summary" => "Generate a single #{name}",
+              "operationId" => "generate#{name}",
+              "parameters" => generation_parameters,
+              "responses" => {
+                "200" => {
+                  "description" => "Generated #{name}",
+                  "content" => {
+                    "application/json" => {
+                      "schema" => { "$ref" => "#/components/schemas/#{name}" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+          
+          # Generate many
+          paths["/api/#{snake_name}/batch"] = {
+            "get" => {
+              "tags" => [name],
+              "summary" => "Generate multiple #{name} records",
+              "operationId" => "generateMany#{name}s",
+              "parameters" => batch_generation_parameters,
+              "responses" => {
+                "200" => {
+                  "description" => "Generated #{name} records",
+                  "content" => {
+                    "application/json" => {
+                      "schema" => {
+                        "type" => "object",
+                        "properties" => {
+                          "data" => {
+                            "type" => "array",
+                            "items" => { "$ref" => "#/components/schemas/#{name}" }
+                          },
+                          "meta" => {
+                            "type" => "object",
+                            "properties" => {
+                              "count" => { "type" => "integer" },
+                              "seed" => { "type" => "integer" },
+                              "mode" => { "type" => "string" }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "post" => {
+              "tags" => [name],
+              "summary" => "Generate #{name} records with overrides",
+              "operationId" => "generateMany#{name}sWithOverrides",
+              "requestBody" => {
+                "content" => {
+                  "application/json" => {
+                    "schema" => { "$ref" => "#/components/schemas/GenerationRequest" }
+                  }
+                }
+              },
+              "responses" => {
+                "200" => {
+                  "description" => "Generated #{name} records",
+                  "content" => {
+                    "application/json" => {
+                      "schema" => {
+                        "type" => "array",
+                        "items" => { "$ref" => "#/components/schemas/#{name}" }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+          
+          # Stream endpoint
+          paths["/api/#{snake_name}/stream"] = {
+            "get" => {
+              "tags" => [name],
+              "summary" => "Stream #{name} records (NDJSON)",
+              "operationId" => "stream#{name}s",
+              "parameters" => batch_generation_parameters,
+              "responses" => {
+                "200" => {
+                  "description" => "Streamed #{name} records",
+                  "content" => {
+                    "application/x-ndjson" => {
+                      "schema" => { "$ref" => "#/components/schemas/#{name}" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+          
+          # Schema info endpoint
+          paths["/api/#{snake_name}/schema"] = {
+            "get" => {
+              "tags" => [name],
+              "summary" => "Get #{name} schema definition",
+              "operationId" => "get#{name}Schema",
+              "responses" => {
+                "200" => {
+                  "description" => "Schema definition",
+                  "content" => {
+                    "application/json" => {
+                      "schema" => { "$ref" => "#/components/schemas/SchemaDefinition" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        end
+        
+        paths
+      end
+
+      def generation_parameters
+        [
+          {
+            "name" => "seed",
+            "in" => "query",
+            "description" => "Random seed for deterministic generation",
+            "schema" => { "type" => "integer" }
+          },
+          {
+            "name" => "mode",
+            "in" => "query",
+            "description" => "Generation mode",
+            "schema" => {
+              "type" => "string",
+              "enum" => %w[random edge invalid hostile mixed]
+            }
+          }
+        ]
+      end
+
+      def batch_generation_parameters
+        generation_parameters + [
+          {
+            "name" => "count",
+            "in" => "query",
+            "description" => "Number of records to generate",
+            "schema" => { "type" => "integer", "default" => 10, "minimum" => 1, "maximum" => 10000 }
+          }
+        ]
+      end
+
+      def build_components
+        {
+          "schemas" => build_schemas,
+          "parameters" => build_common_parameters
+        }
+      end
+
+      def build_schemas
+        schemas = {}
+        
+        # Schema definitions
+        @registry.names.each do |name|
+          schema = @registry.schema(name)
+          schemas[name] = schema_to_openapi(schema)
+        end
+        
+        # Common schemas
+        schemas["GenerationRequest"] = {
+          "type" => "object",
+          "properties" => {
+            "count" => { "type" => "integer", "default" => 10 },
+            "seed" => { "type" => "integer" },
+            "mode" => { "type" => "string", "enum" => %w[random edge invalid hostile mixed] },
+            "overrides" => { "type" => "object", "additionalProperties" => true }
+          }
+        }
+        
+        schemas["SchemaDefinition"] = {
+          "type" => "object",
+          "properties" => {
+            "name" => { "type" => "string" },
+            "fields" => {
+              "type" => "array",
+              "items" => {
+                "type" => "object",
+                "properties" => {
+                  "name" => { "type" => "string" },
+                  "type" => { "type" => "string" },
+                  "optional" => { "type" => "boolean" },
+                  "nullable" => { "type" => "boolean" }
+                }
+              }
+            },
+            "behaviors" => {
+              "type" => "array",
+              "items" => { "type" => "object" }
+            }
+          }
+        }
+        
+        schemas["Error"] = {
+          "type" => "object",
+          "properties" => {
+            "error" => { "type" => "string" },
+            "message" => { "type" => "string" },
+            "code" => { "type" => "integer" }
+          }
+        }
+        
+        schemas
+      end
+
+      def schema_to_openapi(schema)
+        properties = {}
+        required = []
+        
+        schema.fields.each do |field|
+          properties[field.name] = field_to_openapi(field)
+          required << field.name unless field.optional?
+        end
+        
+        result = {
+          "type" => "object",
+          "properties" => properties
+        }
+        
+        result["required"] = required if required.any?
+        result
+      end
+
+      def field_to_openapi(field)
+        type_name = field.type_name
+        
+        # Handle arrays
+        if type_name == "array"
+          element = field.type_args[:element]
+          items = if @registry.schema?(element.to_s)
+                    { "$ref" => "#/components/schemas/#{element}" }
+                  else
+                    TYPE_MAP[element.to_s] || { "type" => "string" }
+                  end
+          
+          result = { "type" => "array", "items" => items }
+          
+          if (size = field.type_args[:size])
+            result["minItems"] = size.min if size.respond_to?(:min)
+            result["maxItems"] = size.max if size.respond_to?(:max)
+          end
+          
+          return result
+        end
+        
+        # Handle enums
+        if type_name == "enum"
+          values = field.type_args[:values]&.map { |v| v.respond_to?(:value) ? v.value : v.to_s }
+          return { "type" => "string", "enum" => values || [] }
+        end
+        
+        # Handle const
+        if type_name == "const"
+          return { "const" => field.type_args[:value] }
+        end
+        
+        # Handle references
+        if @registry.schema?(type_name)
+          return { "$ref" => "#/components/schemas/#{type_name}" }
+        end
+        
+        # Standard type mapping
+        TYPE_MAP[type_name]&.dup || { "type" => "string" }
+      end
+
+      def build_common_parameters
+        {
+          "seedParam" => {
+            "name" => "seed",
+            "in" => "query",
+            "description" => "Random seed for deterministic generation",
+            "schema" => { "type" => "integer" }
+          },
+          "modeParam" => {
+            "name" => "mode",
+            "in" => "query",
+            "description" => "Generation mode",
+            "schema" => {
+              "type" => "string",
+              "enum" => %w[random edge invalid hostile mixed]
+            }
+          },
+          "countParam" => {
+            "name" => "count",
+            "in" => "query",
+            "description" => "Number of records to generate",
+            "schema" => { "type" => "integer", "default" => 10 }
+          }
+        }
+      end
+
+      def to_snake_case(str)
+        str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
+      end
+    end
+  end
+end