rapitapir 0.1.0

data/lib/rapitapir/sinatra/resource_builder.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Sinatra
+    # Resource builder for creating RESTful API endpoints
+    # Follows Open/Closed Principle - extensible for new resource types
+    class ResourceBuilder
+      def initialize(app, base_path, schema, **options)
+        @app = app
+        @base_path = base_path.chomp('/')
+        @schema = schema
+        @options = options
+        @endpoints = []
+      end
+
+      # Enable standard CRUD operations
+      def crud(except: [], only: nil, **handlers, &block)
+        operations = only || %i[index show create update destroy]
+        operations -= except if except.any?
+
+        # If a block is given, evaluate it in the context of this ResourceBuilder
+        # This allows method calls like: index { BookStore.all }
+        if block_given?
+          instance_eval(&block)
+        else
+          # Legacy style with handlers hash
+          operations.each do |operation|
+            send(operation, &handlers[operation]) if respond_to?(operation, true)
+          end
+        end
+      end
+
+      # List all resources (GET /resources)
+      def index(**options, &handler)
+        handler ||= proc { [] }
+
+        endpoint = build_index_endpoint(options)
+        @app.endpoint(endpoint, &handler)
+      end
+
+      def build_index_endpoint(options)
+        RapiTapir.get(@base_path)
+                 .summary(options[:summary] || "List all #{resource_name}")
+                 .description(options[:description] || "Retrieve a list of #{resource_name}")
+                 .then { |ep| add_pagination_params(ep) }
+                 .ok(RapiTapir::Types.array(@schema))
+                 .build
+      end
+
+      def add_pagination_params(endpoint)
+        endpoint.query(:limit, RapiTapir::Types.optional(RapiTapir::Types.integer),
+                       description: 'Maximum number of results')
+                .query(:offset, RapiTapir::Types.optional(RapiTapir::Types.integer),
+                       description: 'Number of results to skip')
+      end
+
+      # Get specific resource (GET /resources/:id)
+      def show(**options, &handler)
+        handler ||= proc { {} }
+
+        endpoint = RapiTapir.get("#{@base_path}/:id")
+                            .summary(options[:summary] || "Get #{resource_name}")
+                            .description(options[:description] || "Retrieve a specific #{resource_name} by ID")
+                            .path_param(:id, RapiTapir::Types.integer, description: "#{resource_name.capitalize} ID")
+                            .ok(@schema)
+                            .build
+
+        @app.endpoint(endpoint, &handler)
+      end
+
+      # Create new resource (POST /resources)
+      def create(**options, &handler)
+        handler ||= proc { {} }
+
+        endpoint = RapiTapir.post(@base_path)
+                            .summary(options[:summary] || "Create #{resource_name}")
+                            .description(options[:description] || "Create a new #{resource_name}")
+                            .json_body(@schema)
+                            .created(@schema)
+                            .build
+
+        @app.endpoint(endpoint, &handler)
+      end
+
+      # Update resource (PUT /resources/:id)
+      def update(**options, &handler)
+        handler ||= proc { {} }
+
+        endpoint = RapiTapir.put("#{@base_path}/:id")
+                            .summary(options[:summary] || "Update #{resource_name}")
+                            .description(options[:description] || "Update an existing #{resource_name}")
+                            .path_param(:id, RapiTapir::Types.integer, description: "#{resource_name.capitalize} ID")
+                            .json_body(@schema)
+                            .ok(@schema)
+                            .build
+
+        @app.endpoint(endpoint, &handler)
+      end
+
+      # Delete resource (DELETE /resources/:id)
+      def destroy(**options, &handler)
+        handler ||= proc { status 204 }
+
+        endpoint = RapiTapir.delete("#{@base_path}/:id")
+                            .summary(options[:summary] || "Delete #{resource_name}")
+                            .description(options[:description] || "Delete a #{resource_name}")
+                            .path_param(:id, RapiTapir::Types.integer, description: "#{resource_name.capitalize} ID")
+                            .no_content
+                            .build
+
+        @app.endpoint(endpoint, &handler)
+      end
+
+      # Custom endpoint within the resource
+      def custom(method, path, summary: nil, configure: nil, **_options, &handler)
+        full_path = path.start_with?('/') ? path : "#{@base_path}/#{path}"
+
+        endpoint = RapiTapir.send(method, full_path)
+        endpoint = endpoint.summary(summary) if summary
+        endpoint = configure.call(endpoint) if configure
+
+        @app.endpoint(endpoint.build, &handler)
+      end
+
+      private
+
+      def resource_name
+        @resource_name ||= @base_path.split('/').last.singularize
+      end
+    end
+  end
+end
+
+# String extensions for pluralization/singularization
+class String
+  def pluralize
+    case self
+    when /s$/ then self
+    when /y$/ then sub(/y$/, 'ies')
+    when /(ch|sh|x|z)$/ then "#{self}es"
+    else "#{self}s"
+    end
+  end
+
+  def singularize
+    case self
+    when /ies$/ then sub(/ies$/, 'y')
+    when /s$/ then chomp('s')
+    else self
+    end
+  end
+end

data/lib/rapitapir/sinatra/swagger_ui_generator.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module RapiTapir
+  module Sinatra
+    # Swagger UI HTML generator
+    # Follows Single Responsibility Principle - only generates UI HTML
+    class SwaggerUIGenerator
+      def initialize(openapi_path, api_info)
+        @openapi_path = openapi_path
+        @api_info = api_info
+      end
+
+      def generate
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>#{@api_info[:title]} - API Documentation</title>
+            <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css" />
+            <style>
+              #{custom_styles}
+            </style>
+          </head>
+          <body>
+            #{header_banner}
+            <div id="swagger-ui"></div>
+            <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js"></script>
+            <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-standalone-preset.js"></script>
+            <script>
+              #{swagger_ui_config}
+            </script>
+          </body>
+          </html>
+        HTML
+      end
+
+      private
+
+      def custom_styles
+        <<~CSS
+          html {
+            box-sizing: border-box;
+            overflow: -moz-scrollbars-vertical;
+            overflow-y: scroll;
+          }
+          *, *:before, *:after {
+            box-sizing: inherit;
+          }
+          body {
+            margin: 0;
+            background: #fafafa;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+          }
+          .swagger-ui .topbar {
+            display: none;
+          }
+          .info-banner {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 30px 20px;
+            text-align: center;
+            margin-bottom: 20px;
+            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+          }
+          .info-banner h1 {
+            margin: 0 0 10px 0;
+            font-size: 28px;
+            font-weight: 600;
+          }
+          .info-banner p {
+            margin: 0;
+            opacity: 0.9;
+            font-size: 16px;
+          }
+          .info-banner .badge {
+            display: inline-block;
+            background: rgba(255, 255, 255, 0.2);
+            padding: 4px 12px;
+            border-radius: 20px;
+            font-size: 14px;
+            margin: 10px 5px 0 0;
+          }
+          .swagger-ui .scheme-container {
+            padding: 30px 0;
+            background: white;
+            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+          }
+        CSS
+      end
+
+      def header_banner
+        <<~HTML
+          <div class="info-banner">
+            <h1>#{@api_info[:title]}</h1>
+            <p>#{@api_info[:description]}</p>
+            <div>
+              <span class="badge">v#{@api_info[:version]}</span>
+              <span class="badge">🚀 RapiTapir</span>
+              <span class="badge">⚡ Auto-generated</span>
+            </div>
+          </div>
+        HTML
+      end
+
+      def swagger_ui_config
+        <<~JS
+          window.onload = function() {
+            const ui = SwaggerUIBundle({
+              url: '#{@openapi_path}',
+              dom_id: '#swagger-ui',
+              deepLinking: true,
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset
+              ],
+              plugins: [
+                SwaggerUIBundle.plugins.DownloadUrl
+              ],
+              layout: "StandaloneLayout",
+              tryItOutEnabled: true,
+              supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'],
+              validatorUrl: null,
+              docExpansion: 'list',
+              filter: true,
+              showExtensions: true,
+              showCommonExtensions: true,
+              defaultModelsExpandDepth: 2,
+              defaultModelExpandDepth: 2,
+              displayRequestDuration: true,
+              requestInterceptor: function(request) {
+                // Add custom request headers or modify requests here
+                return request;
+              },
+              responseInterceptor: function(response) {
+                // Handle responses here
+                return response;
+              },
+              onComplete: function() {
+                console.log('🚀 RapiTapir Swagger UI loaded successfully');
+                console.log('📋 OpenAPI spec auto-generated from RapiTapir endpoints');
+                console.log('🔧 Powered by RapiTapir Sinatra Extension');
+              },
+              onFailure: function(error) {
+                console.error('Failed to load Swagger UI:', error);
+              }
+            });
+
+            // Custom enhancements
+            setTimeout(function() {
+              // Add custom styling or behavior after UI loads
+              const infoSection = document.querySelector('.swagger-ui .info');
+              if (infoSection && !infoSection.querySelector('.rapitapir-badge')) {
+                const badge = document.createElement('div');
+                badge.className = 'rapitapir-badge';
+                badge.innerHTML = '<small style="color: #666; font-style: italic;">Generated with RapiTapir Sinatra Extension</small>';
+                infoSection.appendChild(badge);
+              }
+            }, 1000);
+          };
+        JS
+      end
+    end
+  end
+end

data/lib/rapitapir/sinatra_rapitapir.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require_relative 'sinatra/extension'
+
+module RapiTapir
+  # SinatraRapiTapir - A clean base class for RapiTapir APIs
+  #
+  # This class provides the most ergonomic way to create RapiTapir APIs:
+  #
+  # class MyAPI < RapiTapir::SinatraRapiTapir
+  #   rapitapir do
+  #     info(title: 'My API', version: '1.0.0')
+  #     development_defaults!
+  #   end
+  #
+  #   endpoint(
+  #     GET('/hello').ok(string_response).build
+  #   ) { { message: 'Hello!' } }
+  # end
+  #
+  # Features automatically included:
+  # - Enhanced HTTP verb DSL (GET, POST, PUT, etc.)
+  # - RapiTapir extension with all features
+  # - Clean inheritance-based setup
+  class SinatraRapiTapir < ::Sinatra::Base
+    # Automatically register the RapiTapir extension
+    register RapiTapir::Sinatra::Extension
+
+    # Include a helpful message for developers
+    configure :development do
+      puts '🚀 Using RapiTapir::SinatraRapiTapir base class'
+      puts '✨ Enhanced HTTP verb DSL automatically available'
+      puts '🔧 Extension features: health checks, CORS, docs, and more'
+    end
+  end
+end
+
+# Also make it available at the top level for convenience
+SinatraRapiTapir = RapiTapir::SinatraRapiTapir

data/lib/rapitapir/types/array.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RapiTapir
+  module Types
+    # Array type for validating array values with element type constraints
+    # Validates arrays with specific element types and size constraints
+    class Array < Base
+      attr_reader :item_type
+
+      def initialize(item_type, min_items: nil, max_items: nil, unique_items: false, **options)
+        @item_type = item_type
+        super(
+          min_items: min_items,
+          max_items: max_items,
+          unique_items: unique_items,
+          **options
+        )
+      end
+
+      protected
+
+      def validate_type(value)
+        return ["Expected array, got #{value.class}"] unless value.is_a?(::Array)
+
+        []
+      end
+
+      def validate_constraints(value)
+        errors = []
+
+        errors.concat(validate_length_constraints(value))
+        errors.concat(validate_uniqueness_constraint(value))
+        errors.concat(validate_item_types(value))
+
+        errors
+      end
+
+      def validate_length_constraints(value)
+        errors = []
+
+        errors.concat(validate_min_items_constraint(value))
+        errors.concat(validate_max_items_constraint(value))
+
+        errors
+      end
+
+      def validate_min_items_constraint(value)
+        return [] unless constraints[:min_items] && value.length < constraints[:min_items]
+
+        ["Array length #{value.length} is below minimum #{constraints[:min_items]}"]
+      end
+
+      def validate_max_items_constraint(value)
+        return [] unless constraints[:max_items] && value.length > constraints[:max_items]
+
+        ["Array length #{value.length} exceeds maximum #{constraints[:max_items]}"]
+      end
+
+      def validate_uniqueness_constraint(value)
+        return [] unless constraints[:unique_items] && value.uniq.length != value.length
+
+        ['Array contains duplicate items but must be unique']
+      end
+
+      def validate_item_types(value)
+        errors = []
+
+        value.each_with_index do |item, index|
+          item_result = item_type.validate(item)
+          next if item_result[:valid]
+
+          item_result[:errors].each do |error|
+            errors << "Item at index #{index}: #{error}"
+          end
+        end
+
+        errors
+      end
+
+      def coerce_value(value)
+        case value
+        when ::Array
+          coerce_array_value(value)
+        when ::String
+          coerce_string_value(value)
+        else
+          coerce_single_value(value)
+        end
+      rescue JSON::ParserError => e
+        raise CoercionError.new(value, 'Array', "Invalid JSON: #{e.message}")
+      rescue StandardError => e
+        raise CoercionError.new(value, 'Array', e.message)
+      end
+
+      def coerce_array_value(value)
+        value.map { |item| item_type.coerce(item) }
+      end
+
+      def coerce_string_value(value)
+        # Try to parse as JSON array
+        require 'json'
+        parsed = JSON.parse(value)
+        raise CoercionError.new(value, 'Array', 'JSON string did not parse to array') unless parsed.is_a?(::Array)
+
+        parsed.map { |item| item_type.coerce(item) }
+      end
+
+      def coerce_single_value(value)
+        # Wrap single value in array
+        [item_type.coerce(value)]
+      end
+
+      def json_type
+        'array'
+      end
+
+      def apply_constraints_to_schema(schema)
+        super
+        apply_array_specific_constraints(schema)
+      end
+
+      def apply_array_specific_constraints(schema)
+        schema[:items] = item_type.to_json_schema
+        apply_size_constraints(schema)
+        apply_uniqueness_constraint(schema)
+      end
+
+      def apply_size_constraints(schema)
+        schema[:minItems] = constraints[:min_items] if constraints[:min_items]
+        schema[:maxItems] = constraints[:max_items] if constraints[:max_items]
+      end
+
+      def apply_uniqueness_constraint(schema)
+        schema[:uniqueItems] = constraints[:unique_items] if constraints[:unique_items]
+      end
+
+      def to_s
+        item_type_str = format_item_type_string
+        constraint_part = format_constraints_string
+        "Array[#{item_type_str}]#{constraint_part}"
+      end
+
+      def format_item_type_string
+        item_type.respond_to?(:to_s) ? item_type.to_s : item_type.class.name
+      end
+
+      def format_constraints_string
+        constraint_strs = build_constraint_strings
+        constraint_strs.empty? ? '' : "(#{constraint_strs.join(', ')})"
+      end
+
+      def build_constraint_strings
+        constraint_strs = []
+        constraint_strs << "min_items: #{constraints[:min_items]}" if constraints[:min_items]
+        constraint_strs << "max_items: #{constraints[:max_items]}" if constraints[:max_items]
+        constraint_strs << "unique: #{constraints[:unique_items]}" if constraints[:unique_items]
+        constraint_strs
+      end
+    end
+  end
+end