rapitapir 0.1.0

data/lib/rapitapir/openapi/schema_generator.rb

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RapiTapir
+  module OpenAPI
+    # OpenAPI schema generator for RapiTapir endpoints
+    # Converts RapiTapir endpoint definitions to OpenAPI 3.0 specifications
+    class SchemaGenerator
+      attr_reader :endpoints, :info, :servers
+
+      def initialize(endpoints: [], info: {}, servers: [])
+        @endpoints = endpoints
+        @info = default_info.merge(info)
+        @servers = servers.empty? ? default_servers : servers
+      end
+
+      # Generate complete OpenAPI 3.0 specification
+      def generate
+        {
+          openapi: '3.0.3',
+          info: @info,
+          servers: @servers,
+          paths: generate_paths,
+          components: generate_components
+        }
+      end
+
+      # Generate as JSON string
+      def to_json(pretty: true)
+        schema = generate
+        if pretty
+          JSON.pretty_generate(schema)
+        else
+          JSON.generate(schema)
+        end
+      end
+
+      # Generate as YAML string
+      def to_yaml
+        require 'yaml'
+        YAML.dump(generate)
+      end
+
+      private
+
+      def default_info
+        {
+          title: 'RapiTapir API',
+          version: '1.0.0',
+          description: 'API generated by RapiTapir'
+        }
+      end
+
+      def default_servers
+        [
+          {
+            url: 'http://localhost:4567',
+            description: 'Development server'
+          }
+        ]
+      end
+
+      def generate_paths
+        paths = {}
+
+        @endpoints.each do |endpoint_data|
+          endpoint = endpoint_data.is_a?(Hash) ? endpoint_data[:endpoint] : endpoint_data
+          # Convert :id format to {id} format for OpenAPI
+          path = convert_path_to_openapi(endpoint.path)
+          method = endpoint.method.to_s.downcase
+
+          paths[path] ||= {}
+          paths[path][method] = generate_operation(endpoint)
+        end
+
+        paths
+      end
+
+      def generate_operation(endpoint)
+        operation = build_base_operation(endpoint)
+
+        add_parameters_to_operation(operation, endpoint)
+        add_request_body_to_operation(operation, endpoint)
+        add_responses_to_operation(operation, endpoint)
+
+        # Remove nil values
+        operation.compact
+      end
+
+      def build_base_operation(endpoint)
+        {
+          summary: endpoint.metadata[:summary] || generate_default_summary(endpoint),
+          description: endpoint.metadata[:description],
+          operationId: generate_operation_id(endpoint),
+          tags: endpoint.metadata[:tags]&.any? ? endpoint.metadata[:tags] : [generate_default_tag(endpoint)]
+        }
+      end
+
+      def add_parameters_to_operation(operation, endpoint)
+        parameters = generate_parameters(endpoint)
+        operation[:parameters] = parameters if parameters.any?
+      end
+
+      def add_request_body_to_operation(operation, endpoint)
+        request_body = generate_request_body(endpoint)
+        operation[:requestBody] = request_body if request_body
+      end
+
+      def add_responses_to_operation(operation, endpoint)
+        operation[:responses] = generate_responses(endpoint)
+      end
+
+      def generate_parameters(endpoint)
+        parameters = []
+
+        endpoint.inputs.each do |input|
+          parameter = build_parameter_for_input(input)
+          parameters << parameter if parameter
+        end
+
+        parameters
+      end
+
+      def build_parameter_for_input(input)
+        case input.kind
+        when :path
+          build_path_parameter(input)
+        when :query
+          build_query_parameter(input)
+        when :header
+          build_header_parameter(input)
+        end
+      end
+
+      def build_path_parameter(input)
+        {
+          name: input.name.to_s,
+          in: 'path',
+          required: true,
+          description: "Path parameter: #{input.name}",
+          schema: type_to_schema(input.type)
+        }
+      end
+
+      def build_query_parameter(input)
+        {
+          name: input.name.to_s,
+          in: 'query',
+          required: input.required?,
+          description: "Query parameter: #{input.name}",
+          schema: type_to_schema(input.type)
+        }
+      end
+
+      def build_header_parameter(input)
+        {
+          name: input.name.to_s,
+          in: 'header',
+          required: input.required?,
+          description: "Header parameter: #{input.name}",
+          schema: type_to_schema(input.type)
+        }
+      end
+
+      def generate_request_body(endpoint)
+        body_input = endpoint.inputs.find { |input| input.kind == :body }
+        return nil unless body_input
+
+        content_type = determine_content_type(body_input)
+
+        {
+          description: 'Request body',
+          required: body_input.required?,
+          content: {
+            content_type => {
+              schema: type_to_schema(body_input.type)
+            }
+          }
+        }
+      end
+
+      def generate_responses(endpoint)
+        responses = {}
+
+        generate_success_responses(endpoint, responses)
+        generate_error_responses(endpoint, responses)
+        add_default_response_if_needed(responses)
+
+        responses
+      end
+
+      def generate_success_responses(endpoint, responses)
+        endpoint.outputs.each do |output|
+          status_code = determine_status_code(output)
+          content_type = determine_output_content_type(output)
+
+          responses[status_code.to_s] = {
+            description: 'Successful response',
+            content: {
+              content_type => {
+                schema: type_to_schema(output.type)
+              }
+            }
+          }
+        end
+      end
+
+      def generate_error_responses(endpoint, responses)
+        endpoint.errors.each do |error_entry|
+          error_response = build_error_response(error_entry)
+          responses[error_response[:status_code].to_s] = error_response[:response]
+        end
+      end
+
+      def build_error_response(error_entry)
+        if error_entry.respond_to?(:status_code)
+          build_enhanced_error_response(error_entry)
+        else
+          build_legacy_error_response(error_entry)
+        end
+      end
+
+      def build_enhanced_error_response(error_entry)
+        status_code = error_entry.status_code
+        description = error_entry.description || 'Error response'
+        schema = type_to_schema(error_entry.type || { error: :string })
+
+        {
+          status_code: status_code,
+          response: {
+            description: description,
+            content: {
+              'application/json' => {
+                schema: schema
+              }
+            }
+          }
+        }
+      end
+
+      def build_legacy_error_response(error_entry)
+        status_code = error_entry[:code] || 400
+        description = error_entry[:description] || 'Error response'
+        schema = type_to_schema(error_entry[:output]&.type || { error: :string })
+
+        {
+          status_code: status_code,
+          response: {
+            description: description,
+            content: {
+              'application/json' => {
+                schema: schema
+              }
+            }
+          }
+        }
+      end
+
+      def add_default_response_if_needed(responses)
+        return unless responses.empty?
+
+        responses['200'] = {
+          description: 'Successful response'
+        }
+      end
+
+      def generate_components
+        {
+          schemas: generate_schema_components
+        }
+      end
+
+      def generate_schema_components
+        # For now, return empty. In the future, we can extract common schemas
+        {}
+      end
+
+      def type_to_schema(type)
+        case type
+        when RapiTapir::Types::String, :string, String
+          { type: 'string' }
+        when RapiTapir::Types::Integer, :integer, Integer
+          { type: 'integer' }
+        when RapiTapir::Types::Float, :number, Float
+          { type: 'number' }
+        when RapiTapir::Types::Boolean, :boolean
+          { type: 'boolean' }
+        else
+          generate_complex_type_schema(type)
+        end
+      end
+
+      def generate_complex_type_schema(type)
+        case type
+        when RapiTapir::Types::Array
+          generate_array_schema(type)
+        when RapiTapir::Types::Hash
+          generate_hash_schema(type)
+        when :date, :datetime
+          generate_date_schema(type)
+        when Array
+          generate_ruby_array_schema(type)
+        else # Default for unknown types, :string, String, and Hash
+          { type: 'string' }
+        end
+      end
+
+      def generate_array_schema(type)
+        { type: 'array', items: type_to_schema(type.item_type) }
+      end
+
+      def generate_hash_schema(type)
+        return { type: 'object' } if type.field_types.empty?
+
+        properties = {}
+        required = []
+
+        type.field_types.each do |key, value|
+          properties[key.to_s] = type_to_schema(value)
+          required << key.to_s unless value.nil?
+        end
+
+        schema = { type: 'object', properties: properties }
+        schema[:required] = required if required.any?
+        schema
+      end
+
+      def generate_date_schema(type)
+        format = type == :date ? 'date' : 'date-time'
+        { type: 'string', format: format }
+      end
+
+      def generate_ruby_array_schema(type)
+        if type.length == 1
+          { type: 'array', items: type_to_schema(type.first) }
+        else
+          { type: 'array', items: { type: 'string' } }
+        end
+      end
+
+      def determine_content_type(input)
+        case input.type
+        when Hash
+          # For hash types, default to JSON
+          return 'application/json'
+        end
+        'application/json'
+      end
+
+      def determine_output_content_type(output)
+        case output.kind
+        when :xml
+          'application/xml'
+        when :html
+          'text/html'
+        else # Default for :json and unknown formats
+          'application/json'
+        end
+      end
+
+      def determine_status_code(output)
+        if output.kind == :status && output.type.is_a?(Integer)
+          output.type
+        else
+          # Default status codes based on output type
+          case output.kind
+          when :json, :xml
+            # JSON and XML responses default to 200
+            return 200
+          end
+          200
+        end
+      end
+
+      def generate_operation_id(endpoint)
+        method = endpoint.method.to_s.downcase
+        path_parts = endpoint.path.split('/').reject(&:empty?).map do |part|
+          part.start_with?(':') ? part[1..] : part
+        end
+
+        "#{method}_#{path_parts.join('_')}"
+      end
+
+      def generate_default_summary(endpoint)
+        method = endpoint.method.to_s.upcase
+        path = endpoint.path
+        "#{method} #{path}"
+      end
+
+      def generate_default_tag(endpoint)
+        # Extract the first path segment as a tag
+        first_segment = endpoint.path.split('/').reject(&:empty?).first
+        first_segment&.capitalize || 'default'
+      end
+
+      def convert_path_to_openapi(path)
+        # Convert "/users/:id" to "/users/{id}" for OpenAPI
+        path.gsub(/:([a-zA-Z_]\w*)/, '{\1}')
+      end
+    end
+  end
+end

data/lib/rapitapir/schema.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative 'types'
+
+module RapiTapir
+  # Schema definition and validation module
+  # Provides tools for defining and validating data schemas
+  module Schema
+    # Error for schema validation failures
+    # Raised when data does not conform to defined schema constraints
+    class ValidationError < StandardError
+      attr_reader :errors
+
+      def initialize(errors)
+        @errors = errors
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        "Schema validation failed:\n#{errors.map { |error| "  - #{error}" }.join("\n")}"
+      end
+    end
+
+    # Define a schema using a block
+    def self.define(&block)
+      builder = SchemaBuilder.new
+      builder.instance_eval(&block)
+      builder.build
+    end
+
+    # Validate a value against a type
+    def self.validate!(value, type)
+      result = type.validate(value)
+      return value if result[:valid]
+
+      raise ValidationError, result[:errors]
+    end
+
+    # Validate a value against a type, returning result
+    def self.validate(value, type)
+      type.validate(value)
+    end
+
+    # Coerce a value using a type
+    def self.coerce(value, type)
+      type.coerce(value)
+    end
+
+    # Create a type from a simplified definition
+    def self.from_definition(definition)
+      case definition
+      when Symbol
+        create_primitive_type(definition)
+      when ::Hash
+        create_type_from_hash(definition)
+      when ::Array
+        create_array_type_from_definition(definition)
+      when Class
+        # Assume it's already a type class
+        definition
+      else
+        raise ArgumentError, "Unknown definition type: #{definition.class}"
+      end
+    end
+
+    def self.create_type_from_hash(definition)
+      if definition.keys == [:type] && definition[:type].is_a?(Symbol)
+        create_primitive_type(definition[:type])
+      else
+        create_object_from_hash(definition)
+      end
+    end
+
+    def self.create_array_type_from_definition(definition)
+      raise ArgumentError, 'Array definition must have exactly one element type' unless definition.length == 1
+
+      Types.array(from_definition(definition.first))
+    end
+
+    PRIMITIVE_TYPE_MAP = {
+      string: -> { Types.string },
+      integer: -> { Types.integer },
+      float: -> { Types.float },
+      boolean: -> { Types.boolean },
+      date: -> { Types.date },
+      datetime: -> { Types.datetime },
+      uuid: -> { Types.uuid },
+      email: -> { Types.email }
+    }.freeze
+
+    def self.create_primitive_type(type_symbol)
+      type_creator = PRIMITIVE_TYPE_MAP[type_symbol]
+      return type_creator.call if type_creator
+
+      raise ArgumentError, "Unknown primitive type: #{type_symbol}"
+    end
+
+    def self.create_object_from_hash(hash_definition)
+      object_type = Types.object
+
+      hash_definition.each do |field_name, field_definition|
+        field_type = from_definition(field_definition)
+        object_type.field(field_name, field_type)
+      end
+
+      object_type
+    end
+
+    # Builder for constructing complex schemas from definitions
+    # Provides a fluent interface for schema creation
+    class SchemaBuilder
+      def initialize
+        @object_type = Types.object
+      end
+
+      def field(name, type_def, required: true, **options)
+        type = Schema.from_definition(type_def)
+        @object_type.field(name, type, required: required, **options)
+      end
+
+      def required_field(name, type_def, **options)
+        field(name, type_def, required: true, **options)
+      end
+
+      def optional_field(name, type_def, **options)
+        field(name, type_def, required: false, **options)
+      end
+
+      def build
+        @object_type
+      end
+    end
+  end
+end