rapitapir 0.1.0

data/examples/simple_auto_derivation_demo.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+puts "=== RapiTapir Auto-Derivation Examples ==="
+
+require_relative '../lib/rapitapir/types'
+
+# 1. JSON Schema Example
+puts "\n1. JSON Schema Auto-Derivation"
+puts "-" * 30
+
+user_schema = {
+  "type" => "object",
+  "properties" => {
+    "name" => { "type" => "string" },
+    "age" => { "type" => "integer" },
+    "active" => { "type" => "boolean" }
+  }
+}
+
+result = RapiTapir::Types.from_json_schema(user_schema)
+puts "✅ Derived schema from JSON Schema"
+puts "Fields: #{result.field_types.keys.join(', ')}"
+
+# 2. OpenStruct Example  
+puts "\n2. OpenStruct Auto-Derivation"
+puts "-" * 30
+
+require 'ostruct'
+config = OpenStruct.new(
+  host: "api.example.com",
+  port: 443,
+  ssl: true
+)
+
+result = RapiTapir::Types.from_open_struct(config)
+puts "✅ Derived schema from OpenStruct"
+puts "Fields: #{result.field_types.keys.join(', ')}"
+
+puts "\n🎉 Auto-derivation working for structured data sources!"
+puts "💡 Focus on sources with explicit type information:"
+puts "   - JSON Schema (API contracts)"
+puts "   - OpenStruct (configuration objects)"
+puts "   - Protobuf (when available)"

data/examples/simple_demo_api.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'lib/rapitapir'
+include RapiTapir::DSL
+
+# Simple API endpoints for demonstration
+RapiTapir.get('/users')
+         .out(json_body([{ id: :integer, name: :string, email: :string }]))
+         .summary('List all users')
+         .description('Retrieve a paginated list of all users in the system')
+
+RapiTapir.post('/users')
+         .in(body({ name: :string, email: :string, password: :string }))
+         .out(status_code(201), json_body({ id: :integer, name: :string, email: :string }))
+         .error_out(400, json_body({ error: :string, validation_errors: [:string] }))
+         .error_out(422, json_body({ error: :string, message: :string }))
+         .summary('Create new user')
+         .description('Create a new user account with the provided information')

data/examples/sinatra/user_app.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'sinatra'
+require 'json'
+require_relative '../../lib/rapitapir'
+require_relative '../../lib/rapitapir/server/sinatra_adapter'
+
+# Example Sinatra app using RapiTapir
+class UserSinatraApp < Sinatra::Base
+  def initialize
+    super
+    @users = {
+      1 => { id: 1, name: 'John Doe', email: 'john@example.com' },
+      2 => { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+    }
+
+    setup_rapitapir_endpoints
+  end
+
+  private
+
+  def setup_rapitapir_endpoints
+    adapter = RapiTapir::Server::SinatraAdapter.new(self)
+
+    # List users endpoint
+    list_endpoint = RapiTapir.get('/users')
+                             .summary('List all users')
+                             .out(RapiTapir::Core::Output.new(kind: :json, type: { users: Array }))
+
+    adapter.register_endpoint(list_endpoint) do |_inputs|
+      { users: @users.values }
+    end
+
+    # Get user by ID endpoint
+    get_endpoint = RapiTapir.get('/users/:id')
+                            .summary('Get user by ID')
+                            .in(RapiTapir::Core::Input.new(kind: :path, name: :id, type: :integer))
+                            .out(RapiTapir::Core::Output.new(kind: :json,
+                                                             type: {
+                                                               id: :integer, name: :string, email: :string
+                                                             }))
+
+    adapter.register_endpoint(get_endpoint) do |inputs|
+      user_id = inputs[:id]
+      user = @users[user_id]
+
+      raise ArgumentError, 'User not found' unless user
+
+      user
+    end
+
+    # Create user endpoint
+    create_endpoint = RapiTapir.post('/users')
+                               .summary('Create a new user')
+                               .in(RapiTapir::Core::Input.new(kind: :body, name: :user_data, type: Hash))
+                               .out(RapiTapir::Core::Output.new(kind: :json,
+                                                                type: {
+                                                                  id: :integer, name: :string, email: :string
+                                                                }))
+
+    adapter.register_endpoint(create_endpoint) do |inputs|
+      user_data = inputs[:user_data]
+      new_id = (@users.keys.max || 0) + 1
+
+      new_user = {
+        id: new_id,
+        name: user_data['name'],
+        email: user_data['email']
+      }
+
+      @users[new_id] = new_user
+      new_user
+    end
+
+    # Update user endpoint
+    update_endpoint = RapiTapir.put('/users/:id')
+                               .summary('Update an existing user')
+                               .in(RapiTapir::Core::Input.new(kind: :path, name: :id, type: :integer))
+                               .in(RapiTapir::Core::Input.new(kind: :body, name: :user_data, type: Hash))
+                               .out(RapiTapir::Core::Output.new(kind: :json,
+                                                                type: {
+                                                                  id: :integer, name: :string, email: :string
+                                                                }))
+
+    adapter.register_endpoint(update_endpoint) do |inputs|
+      user_id = inputs[:id]
+      user_data = inputs[:user_data]
+
+      raise ArgumentError, 'User not found' unless @users[user_id]
+
+      @users[user_id].merge!(
+        name: user_data['name'] || @users[user_id][:name],
+        email: user_data['email'] || @users[user_id][:email]
+      )
+
+      @users[user_id]
+    end
+
+    # Delete user endpoint
+    delete_endpoint = RapiTapir.delete('/users/:id')
+                               .summary('Delete a user')
+                               .in(RapiTapir::Core::Input.new(kind: :path, name: :id, type: :integer))
+                               .out(RapiTapir::Core::Output.new(kind: :json, type: { message: :string }))
+
+    adapter.register_endpoint(delete_endpoint) do |inputs|
+      user_id = inputs[:id]
+
+      raise ArgumentError, 'User not found' unless @users[user_id]
+
+      @users.delete(user_id)
+      { message: "User #{user_id} deleted successfully" }
+    end
+  end
+end
+
+# Run the app if this file is executed directly
+if __FILE__ == $PROGRAM_NAME
+  puts 'Starting RapiTapir Sinatra User API server on http://localhost:4567'
+  puts 'Available endpoints:'
+  puts '  GET    /users       - List all users'
+  puts '  GET    /users/:id   - Get user by ID'
+  puts '  POST   /users       - Create new user'
+  puts '  PUT    /users/:id   - Update user'
+  puts '  DELETE /users/:id   - Delete user'
+
+  UserSinatraApp.run!
+end

data/examples/t_shortcut_demo.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demonstration: T shortcut works immediately without any setup
+
+require_relative '../lib/rapitapir'
+require_relative '../lib/rapitapir/sinatra_rapitapir'
+
+puts "🎯 Testing automatic T shortcut availability..."
+puts
+
+# Test 1: Top-level usage
+puts "✅ Top-level usage:"
+BOOK_SCHEMA = T.hash({
+  "id" => T.integer,
+  "title" => T.string(min_length: 1),
+  "published" => T.boolean
+})
+puts "   BOOK_SCHEMA = T.hash(...) ✓"
+puts "   Schema type: #{BOOK_SCHEMA.class}"
+puts
+
+# Test 2: Inside a class
+puts "✅ Inside a class:"
+class DemoAPI < SinatraRapiTapir
+  USER_SCHEMA = T.hash({
+    "name" => T.string,
+    "email" => T.email,
+    "age" => T.optional(T.integer(min: 0))
+  })
+  
+  puts "   USER_SCHEMA = T.hash(...) ✓"
+  puts "   Schema type: #{USER_SCHEMA.class}"
+end
+puts
+
+# Test 3: Complex nested types
+puts "✅ Complex nested types:"
+COMPLEX_SCHEMA = T.hash({
+  "user" => T.hash({
+    "profile" => T.optional(T.hash({
+      "preferences" => T.array(T.string),
+      "settings" => T.hash({
+        "theme" => T.string,
+        "notifications" => T.boolean
+      })
+    }))
+  }),
+  "metadata" => T.hash({
+    "version" => T.string,
+    "timestamp" => T.datetime
+  })
+})
+puts "   Complex nested schema created ✓"
+puts "   Schema type: #{COMPLEX_SCHEMA.class}"
+puts
+
+puts "🎉 All tests passed! T shortcut works everywhere automatically!"
+puts "📝 No manual setup required - just `require 'rapitapir'` and use T.* anywhere!"

data/examples/user_api.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative '../lib/rapitapir'
+
+# Example: User Management API
+module UserAPI
+  extend RapiTapir::DSL
+
+  # GET /users - List all users
+  LIST_USERS = RapiTapir.get('/users')
+                        .in(query(:page, :integer, optional: true))
+                        .in(query(:limit, :integer, optional: true))
+                        .in(query(:search, :string, optional: true))
+                        .in(header(:authorization, :string))
+                        .out(status_code(200))
+                        .out(json_body({
+                                         users: [{ id: :integer, name: :string, email: :string }],
+                                         total: :integer,
+                                         page: :integer,
+                                         limit: :integer
+                                       }))
+                        .error_out(401, json_body({ error: :string }))
+                        .error_out(500, json_body({ error: :string }))
+                        .description('Retrieve a paginated list of users')
+                        .summary('List users')
+                        .tag('users')
+
+  # GET /users/:id - Get specific user
+  GET_USER = RapiTapir.get('/users/:id')
+                      .in(path_param(:id, :integer))
+                      .in(header(:authorization, :string))
+                      .out(status_code(200))
+                      .out(json_body({ id: :integer, name: :string, email: :string, created_at: :datetime }))
+                      .error_out(401, json_body({ error: :string }))
+                      .error_out(404, json_body({ error: :string }))
+                      .error_out(500, json_body({ error: :string }))
+                      .description('Retrieve a specific user by ID')
+                      .summary('Get user')
+                      .tag('users')
+
+  # POST /users - Create new user
+  CREATE_USER = RapiTapir.post('/users')
+                         .in(header(:authorization, :string))
+                         .in(header(:'content-type', :string))
+                         .in(body({ name: :string, email: :string, password: :string }))
+                         .out(status_code(201))
+                         .out(json_body({ id: :integer, name: :string, email: :string, created_at: :datetime }))
+                         .error_out(400, json_body({ error: :string, details: :string }))
+                         .error_out(401, json_body({ error: :string }))
+                         .error_out(422, json_body({ error: :string,
+                                                     validation_errors: [{ field: :string, message: :string }] }))
+                         .error_out(500, json_body({ error: :string }))
+                         .description('Create a new user account')
+                         .summary('Create user')
+                         .tag('users')
+
+  # PUT /users/:id - Update user
+  UPDATE_USER = RapiTapir.put('/users/:id')
+                         .in(path_param(:id, :integer))
+                         .in(header(:authorization, :string))
+                         .in(header(:'content-type', :string))
+                         .in(body({ name: :string, email: :string }))
+                         .out(status_code(200))
+                         .out(json_body({ id: :integer, name: :string, email: :string, updated_at: :datetime }))
+                         .error_out(400, json_body({ error: :string, details: :string }))
+                         .error_out(401, json_body({ error: :string }))
+                         .error_out(404, json_body({ error: :string }))
+                         .error_out(422, json_body({ error: :string,
+                                                     validation_errors: [{ field: :string, message: :string }] }))
+                         .error_out(500, json_body({ error: :string }))
+                         .description('Update an existing user')
+                         .summary('Update user')
+                         .tag('users')
+
+  # DELETE /users/:id - Delete user
+  DELETE_USER = RapiTapir.delete('/users/:id')
+                         .in(path_param(:id, :integer))
+                         .in(header(:authorization, :string))
+                         .out(status_code(204))
+                         .error_out(401, json_body({ error: :string }))
+                         .error_out(404, json_body({ error: :string }))
+                         .error_out(500, json_body({ error: :string }))
+                         .description('Delete a user account')
+                         .summary('Delete user')
+                         .tag('users')
+
+  # POST /users/login - User authentication
+  LOGIN_USER = RapiTapir.post('/users/login')
+                        .in(header(:'content-type', :string))
+                        .in(body({ email: :string, password: :string }))
+                        .out(status_code(200))
+                        .out(json_body({
+                                         user: { id: :integer, name: :string, email: :string },
+                                         token: :string,
+                                         expires_at: :datetime
+                                       }))
+                        .error_out(400, json_body({ error: :string }))
+                        .error_out(401, json_body({ error: :string }))
+                        .error_out(500, json_body({ error: :string }))
+                        .description('Authenticate user and return access token')
+                        .summary('User login')
+                        .tag('authentication')
+
+  # Example usage and validation
+  def self.demo
+    puts '=== RapiTapir User API Demo ==='
+    puts
+
+    # Example 1: Valid user creation
+    puts '1. Valid user creation:'
+    input_data = {
+      body: { name: 'John Doe', email: 'john@example.com', password: 'secret123' }
+    }
+    output_data = {
+      id: 1,
+      name: 'John Doe',
+      email: 'john@example.com',
+      created_at: DateTime.now
+    }
+
+    begin
+      CREATE_USER.validate!(input_data, output_data)
+      puts '✓ Validation passed'
+    rescue StandardError => e
+      puts "✗ Validation failed: #{e.message}"
+    end
+    puts
+
+    # Example 2: Invalid user creation (missing required field)
+    puts '2. Invalid user creation (missing password):'
+    invalid_input = {
+      body: { name: 'John Doe', email: 'john@example.com' }
+    }
+
+    begin
+      CREATE_USER.validate!(invalid_input, output_data)
+      puts '✓ Validation passed'
+    rescue StandardError => e
+      puts "✗ Validation failed: #{e.message}"
+    end
+    puts
+
+    # Example 3: Valid user listing
+    puts '3. Valid user listing:'
+    list_input = {}
+    list_output = {
+      users: [
+        { id: 1, name: 'John Doe', email: 'john@example.com' },
+        { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+      ],
+      total: 2,
+      page: 1,
+      limit: 10
+    }
+
+    begin
+      LIST_USERS.validate!(list_input, list_output)
+      puts '✓ Validation passed'
+    rescue StandardError => e
+      puts "✗ Validation failed: #{e.message}"
+    end
+    puts
+
+    # Example 4: Endpoint metadata
+    puts '4. Endpoint metadata:'
+    puts 'GET /users:'
+    puts "  Description: #{GET_USER.metadata[:description]}"
+    puts "  Summary: #{GET_USER.metadata[:summary]}"
+    puts "  Tag: #{GET_USER.metadata[:tag]}"
+    puts "  Inputs: #{GET_USER.inputs.length}"
+    puts "  Outputs: #{GET_USER.outputs.length}"
+    puts "  Error responses: #{GET_USER.errors.length}"
+    puts
+
+    # Example 5: Serialization
+    puts '5. Output serialization:'
+    json_output = CREATE_USER.outputs.find { |o| o.kind == :json }
+    if json_output
+      serialized = json_output.serialize(output_data)
+      puts "JSON: #{serialized}"
+    end
+    puts
+
+    puts '=== Demo Complete ==='
+  end
+end
+
+# Run the demo if this file is executed directly
+UserAPI.demo if __FILE__ == $PROGRAM_NAME

data/examples/working_getting_started.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# RapiTapir Sinatra Extension - WORKING Getting Started Example
+#
+# This is a simplified version that actually works with Sinatra!
+
+# Check for Sinatra availability
+begin
+  require 'sinatra/base'
+  SINATRA_AVAILABLE = true
+rescue LoadError
+  SINATRA_AVAILABLE = false
+  puts '⚠️  Sinatra not available. Install with: gem install sinatra'
+  puts '🔄 Running in demo mode instead...'
+end
+
+require_relative '../lib/rapitapir'
+
+# Only require SinatraAdapter if Sinatra is available
+if SINATRA_AVAILABLE
+  require_relative '../lib/rapitapir/server/sinatra_adapter'
+  require_relative '../lib/rapitapir/openapi/schema_generator'
+  require_relative '../lib/rapitapir/sinatra/swagger_ui_generator'
+end
+
+# Simple in-memory data store
+class BookStore
+  @@books = [
+    { id: 1, title: 'The Ruby Programming Language', author: 'Matz', isbn: '978-0596516178', published: true },
+    { id: 2, title: 'Metaprogramming Ruby', author: 'Paolo Perrotta', isbn: '978-1934356470', published: true }
+  ]
+  @@next_id = 3
+
+  def self.all
+    @@books
+  end
+
+  def self.find(id)
+    @@books.find { |book| book[:id] == id.to_i }
+  end
+
+  def self.create(attrs)
+    book = attrs.merge(id: @@next_id)
+    @@next_id += 1
+    @@books << book
+    book
+  end
+
+  def self.published
+    @@books.select { |book| book[:published] }
+  end
+end
+
+# Define the book schema
+BOOK_SCHEMA = RapiTapir::Types.hash({
+                                      'id' => RapiTapir::Types.integer,
+                                      'title' => RapiTapir::Types.string,
+                                      'author' => RapiTapir::Types.string,
+                                      'isbn' => RapiTapir::Types.string,
+                                      'published' => RapiTapir::Types.boolean
+                                    })
+
+# WORKING Bookstore API - simplified but effective!
+if SINATRA_AVAILABLE
+  class WorkingBookstoreAPI < Sinatra::Base
+    configure do
+      # Create the RapiTapir adapter - this is the key!
+      set :rapitapir, RapiTapir::Server::SinatraAdapter.new(self)
+      puts '📝 RapiTapir integration enabled'
+    end
+
+    # OpenAPI JSON endpoint - clean and simple
+    get '/openapi.json' do
+      content_type :json
+      endpoints = settings.rapitapir.endpoints.map { |ep_data| ep_data[:endpoint] }
+
+      generator = RapiTapir::OpenAPI::SchemaGenerator.new(
+        endpoints: endpoints,
+        info: {
+          title: 'WORKING Bookstore API',
+          description: 'A simple bookstore API built with RapiTapir and Sinatra - WORKING VERSION!',
+          version: '1.0.0'
+        },
+        servers: [{ url: 'http://localhost:4567', description: 'Development server' }]
+      )
+
+      generator.to_json
+    end
+
+    # Swagger UI documentation endpoint - clean and simple
+    get '/docs' do
+      content_type :html
+      api_info = {
+        title: 'WORKING Bookstore API',
+        description: 'A simple bookstore API built with RapiTapir and Sinatra - WORKING VERSION!'
+      }
+
+      RapiTapir::Sinatra::SwaggerUIGenerator.new('/openapi.json', api_info).generate
+    end
+
+    # Health check - super simple
+    health_endpoint = RapiTapir.get('/health')
+                               .summary('Health check')
+                               .ok(RapiTapir::Types.hash({ 'status' => RapiTapir::Types.string }))
+                               .build
+
+    settings.rapitapir.register_endpoint(health_endpoint) { { status: 'healthy' } }
+
+    # List all books
+    list_books_endpoint = RapiTapir.get('/books')
+                                   .summary('List all books')
+                                   .ok(RapiTapir::Types.array(BOOK_SCHEMA))
+                                   .build
+
+    settings.rapitapir.register_endpoint(list_books_endpoint) { BookStore.all }
+
+    # Published books only - custom endpoint (define BEFORE :id route)
+    published_books_endpoint = RapiTapir.get('/books/published')
+                                        .summary('Get published books only')
+                                        .ok(RapiTapir::Types.array(BOOK_SCHEMA))
+                                        .build
+
+    settings.rapitapir.register_endpoint(published_books_endpoint) { BookStore.published }
+
+    # Get book by ID (must come AFTER specific routes like /books/published)
+    get_book_endpoint = RapiTapir.get('/books/:id')
+                                 .summary('Get book by ID')
+                                 .path_param(:id, RapiTapir::Types.integer, description: 'Book ID')
+                                 .ok(BOOK_SCHEMA)
+                                 .build
+
+    settings.rapitapir.register_endpoint(get_book_endpoint) do |inputs|
+      book = BookStore.find(inputs[:id])
+      halt 404, { error: 'Book not found' }.to_json unless book
+      book
+    end
+
+    configure :development do
+      puts "\n📚 WORKING Bookstore API with RapiTapir"
+      puts '🌐 Health: http://localhost:4567/health'
+      puts '📖 Books: http://localhost:4567/books'
+      puts '📋 Published: http://localhost:4567/books/published'
+      puts '📖 Book by ID: http://localhost:4567/books/1'
+      puts '📚 Documentation: http://localhost:4567/docs'
+      puts '📋 OpenAPI: http://localhost:4567/openapi.json'
+      puts "\n✅ Zero boilerplate, working integration!"
+      puts '💡 Key: Direct use of SinatraAdapter.register_endpoint()'
+      puts '📖 Full OpenAPI 3.0 documentation auto-generated!'
+    end
+  end
+
+  WorkingBookstoreAPI.run! if __FILE__ == $PROGRAM_NAME
+else
+  # Demo mode when Sinatra is not available
+  puts "\n📚 RapiTapir Bookstore API - Demo Mode"
+  puts '=' * 50
+
+  puts "\n✅ Successfully loaded:"
+  puts '   • RapiTapir core'
+  puts '   • Type system'
+  puts '   • Book schema and store'
+
+  puts "\n📊 This working API provides:"
+  puts '   GET    /health           - Health check'
+  puts '   GET    /books            - List all books'
+  puts '   GET    /books/:id        - Get book by ID'
+  puts '   GET    /books/published  - Published books only'
+
+  puts "\n🔧 Working pattern:"
+  puts '   • Create SinatraAdapter: RapiTapir::Server::SinatraAdapter.new(self)'
+  puts '   • Register endpoints: settings.rapitapir.register_endpoint(endpoint, &handler)'
+  puts "   • Build endpoints: RapiTapir.get('/path').summary('...').build"
+  puts '   • Simple and effective!'
+
+  puts "\n💡 To run the working server:"
+  puts '   gem install sinatra rack'
+  puts "   ruby #{__FILE__}"
+
+  puts "\n📖 Sample usage with curl:"
+  puts '   curl http://localhost:4567/health'
+  puts '   curl http://localhost:4567/books'
+  puts '   curl http://localhost:4567/books/1'
+  puts '   curl http://localhost:4567/books/published'
+end