rapitapir 0.1.0

data/examples/openapi/user_api_schema.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/rapitapir'
+require_relative '../../lib/rapitapir/openapi/schema_generator'
+
+# Example script to demonstrate OpenAPI schema generation
+class OpenAPIExample
+  def initialize
+    @endpoints = setup_user_endpoints
+  end
+
+  def generate_schema
+    generator = RapiTapir::OpenAPI::SchemaGenerator.new(
+      endpoints: @endpoints,
+      info: {
+        title: 'User Management API',
+        version: '1.0.0',
+        description: 'A simple user management API built with RapiTapir'
+      },
+      servers: [
+        {
+          url: 'http://localhost:4567',
+          description: 'Development server (Sinatra)'
+        },
+        {
+          url: 'http://localhost:9292',
+          description: 'Development server (Rack)'
+        }
+      ]
+    )
+
+    generator.generate
+  end
+
+  def save_schema(format: :json, pretty: true)
+    schema = generate_schema
+
+    case format
+    when :json
+      content = pretty ? JSON.pretty_generate(schema) : JSON.generate(schema)
+      filename = 'user_api_schema.json'
+    when :yaml
+      require 'yaml'
+      content = YAML.dump(schema)
+      filename = 'user_api_schema.yaml'
+    else
+      raise ArgumentError, "Unsupported format: #{format}"
+    end
+
+    File.write(filename, content)
+    puts "OpenAPI schema saved to #{filename}"
+    puts 'Schema preview:'
+    puts content[0..500] + (content.length > 500 ? '...' : '')
+  end
+
+  private
+
+  def setup_user_endpoints
+    endpoints = []
+
+    # List users endpoint
+    list_endpoint = RapiTapir.get('/users')
+                             .summary('List all users')
+                             .description('Returns a list of all users in the system')
+                             .out(RapiTapir::Core::Output.new(kind: :json,
+                                                              type: { users: [{
+                                                                id: :integer, name: :string, email: :string
+                                                              }] }))
+    endpoints << list_endpoint
+
+    # Get user by ID endpoint
+    get_endpoint = RapiTapir.get('/users/:id')
+                            .summary('Get user by ID')
+                            .description('Returns a single user by their 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
+                                                             }))
+    endpoints << get_endpoint
+
+    # Create user endpoint
+    create_endpoint = RapiTapir.post('/users')
+                               .summary('Create a new user')
+                               .description('Creates a new user with the provided data')
+                               .in(RapiTapir::Core::Input.new(kind: :body, name: :user_data,
+                                                              type: { name: :string, email: :string }))
+                               .out(RapiTapir::Core::Output.new(kind: :json,
+                                                                type: {
+                                                                  id: :integer, name: :string, email: :string
+                                                                }))
+    endpoints << create_endpoint
+
+    # Update user endpoint
+    update_endpoint = RapiTapir.put('/users/:id')
+                               .summary('Update an existing user')
+                               .description('Updates an existing user with the provided data')
+                               .in(RapiTapir::Core::Input.new(kind: :path, name: :id, type: :integer))
+                               .in(RapiTapir::Core::Input.new(kind: :body, name: :user_data,
+                                                              type: { name: :string, email: :string }))
+                               .out(RapiTapir::Core::Output.new(kind: :json,
+                                                                type: {
+                                                                  id: :integer, name: :string, email: :string
+                                                                }))
+    endpoints << update_endpoint
+
+    # Delete user endpoint
+    delete_endpoint = RapiTapir.delete('/users/:id')
+                               .summary('Delete a user')
+                               .description('Deletes a user by their ID')
+                               .in(RapiTapir::Core::Input.new(kind: :path, name: :id, type: :integer))
+                               .out(RapiTapir::Core::Output.new(kind: :json, type: { message: :string }))
+    endpoints << delete_endpoint
+
+    endpoints
+  end
+end
+
+# Run the example if this file is executed directly
+if __FILE__ == $PROGRAM_NAME
+  example = OpenAPIExample.new
+
+  puts 'Generating OpenAPI schema for User Management API...'
+
+  # Generate and save JSON schema
+  example.save_schema(format: :json, pretty: true)
+
+  puts "\n#{'=' * 50}"
+
+  # Generate and save YAML schema
+  example.save_schema(format: :yaml)
+end

data/examples/production_ready_example.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'lib/rapitapir'
+
+puts '🌟 RapiTapir Production-Ready API Example'
+puts '=' * 45
+
+# Define schemas
+User = RapiTapir::Schema.define do
+  field :id, :uuid
+  field :name, :string
+  field :email, :email
+  field :created_at, :datetime
+end
+
+CreateUser = RapiTapir::Schema.define do
+  field :name, :string
+  field :email, :email
+end
+
+Error = RapiTapir::Schema.define do
+  field :error, :string
+  field :message, :string
+  field :code, :integer
+end
+
+# Define a complete REST API using the fluent DSL
+RapiTapir.namespace('/api/v1/users') do
+  bearer_auth('API Token Required')
+  tags('users', 'rest-api')
+
+  error_responses do
+    unauthorized(401, Error, description: 'Invalid or missing token')
+    forbidden(403, Error, description: 'Insufficient permissions')
+    server_error(500, Error, description: 'Internal server error')
+  end
+
+  # GET /api/v1/users - List users with pagination
+  get('/')
+    .summary('List users')
+    .description('Retrieve paginated list of users')
+    .query(:page, :integer, min: 1, default: 1, description: 'Page number')
+    .query(:per_page, :integer, min: 1, max: 100, default: 20, description: 'Items per page')
+    .query(:search, :string, required: false, description: 'Search users by name')
+    .ok(RapiTapir::Types.array(User), description: 'List of users')
+    .bad_request(Error, description: 'Invalid query parameters')
+
+  # GET /api/v1/users/{id} - Get specific user
+  get('/{id}')
+    .summary('Get user by ID')
+    .description('Retrieve a specific user by their unique identifier')
+    .path_param(:id, :uuid, description: 'User unique identifier')
+    .ok(User, description: 'User details')
+    .not_found(Error, description: 'User not found')
+
+  # POST /api/v1/users - Create new user
+  post('/')
+    .summary('Create user')
+    .description('Create a new user account')
+    .json_body(CreateUser, description: 'User data')
+    .requires_scope('users:write')
+    .created(User, description: 'User created successfully')
+    .bad_request(Error, description: 'Invalid user data')
+    .unprocessable_entity(Error, description: 'Validation failed')
+
+  # PUT /api/v1/users/{id} - Update user
+  put('/{id}')
+    .summary('Update user')
+    .description("Update an existing user's information")
+    .path_param(:id, :uuid, description: 'User unique identifier')
+    .json_body(CreateUser, description: 'Updated user data')
+    .requires_scope('users:write')
+    .ok(User, description: 'User updated successfully')
+    .not_found(Error, description: 'User not found')
+    .unprocessable_entity(Error, description: 'Validation failed')
+
+  # DELETE /api/v1/users/{id} - Delete user
+  delete('/{id}')
+    .summary('Delete user')
+    .description('Permanently delete a user account')
+    .path_param(:id, :uuid, description: 'User unique identifier')
+    .requires_scope('users:delete')
+    .no_content(description: 'User deleted successfully')
+    .not_found(Error, description: 'User not found')
+end
+
+puts '✅ Defined complete REST API with 5 endpoints'
+puts '   - GET /api/v1/users (list with pagination)'
+puts '   - GET /api/v1/users/{id} (get by ID)'
+puts '   - POST /api/v1/users (create)'
+puts '   - PUT /api/v1/users/{id} (update)'
+puts '   - DELETE /api/v1/users/{id} (delete)'
+
+puts "\n✅ Features implemented:"
+puts '   - Bearer token authentication'
+puts '   - Scope-based permissions (read/write/delete)'
+puts '   - Full CRUD operations'
+puts '   - Input validation with type constraints'
+puts '   - Comprehensive error responses'
+puts '   - OpenAPI 3.0.3 specification ready'
+puts '   - Production-ready architecture'
+
+puts "\n🚀 RapiTapir Phase 1 Complete!"
+puts '   From documentation tool → Production API framework'
+puts '   Ready for real-world applications! 🎉'

data/examples/rails/users_controller.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# Example Rails controller using RapiTapir
+#
+# To use this in a Rails app:
+# 1. Add this file to app/controllers/
+# 2. Include RapiTapir::Server::Rails::Controller
+# 3. Define endpoints using rapitapir_endpoint
+# 4. Call process_rapitapir_endpoint in your action methods
+
+require_relative '../../lib/rapitapir'
+require_relative '../../lib/rapitapir/server/rails_adapter'
+
+class UsersController < ApplicationController
+  include RapiTapir::Server::Rails::Controller
+
+  before_action :setup_users_data
+
+  # Define RapiTapir endpoints
+  rapitapir_endpoint :index, RapiTapir.get('/users')
+                                      .summary('List all users')
+                                      .description('Returns a list of all users in the system')
+                                      .out(RapiTapir::Core::Output.new(
+                                             kind: :json, type: { users: Array }
+                                           )) do |_inputs|
+    { users: @users.values }
+  end
+
+  rapitapir_endpoint :show, RapiTapir.get('/users/:id')
+                                     .summary('Get user by ID')
+                                     .description('Returns a single user by their 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 }
+                                          )) do |inputs|
+    user_id = inputs[:id]
+    user = @users[user_id]
+
+    raise ArgumentError, 'User not found' unless user
+
+    user
+  end
+
+  rapitapir_endpoint :create, RapiTapir.post('/users')
+                                       .summary('Create a new user')
+                                       .description('Creates a new user with the provided data')
+                                       .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 }
+                                            )) 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
+
+  rapitapir_endpoint :update, RapiTapir.put('/users/:id')
+                                       .summary('Update an existing user')
+                                       .description('Updates an existing user with the provided data')
+                                       .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 }
+                                            )) 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
+
+  rapitapir_endpoint :destroy, RapiTapir.delete('/users/:id')
+                                        .summary('Delete a user')
+                                        .description('Deletes a user by their ID')
+                                        .in(RapiTapir::Core::Input.new(kind: :path, name: :id, type: :integer))
+                                        .out(RapiTapir::Core::Output.new(
+                                               kind: :json, type: { message: :string }
+                                             )) 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
+
+  # Controller actions
+  def index
+    process_rapitapir_endpoint
+  end
+
+  def show
+    process_rapitapir_endpoint
+  end
+
+  def create
+    process_rapitapir_endpoint
+  end
+
+  def update
+    process_rapitapir_endpoint
+  end
+
+  def destroy
+    process_rapitapir_endpoint
+  end
+
+  private
+
+  def setup_users_data
+    @users = {
+      1 => { id: 1, name: 'John Doe', email: 'john@example.com' },
+      2 => { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+    }
+  end
+end
+
+# Example config/routes.rb content:
+#
+# Rails.application.routes.draw do
+#   resources :users, only: [:index, :show, :create, :update, :destroy]
+# end
+#
+# Or using the RailsAdapter for automatic route generation:
+#
+# adapter = RapiTapir::Server::Rails::RailsAdapter.new
+# adapter.register_endpoint(list_endpoint, UsersController, :index)
+# adapter.register_endpoint(show_endpoint, UsersController, :show)
+# # ... etc
+# adapter.generate_routes(Rails.application.routes)

data/examples/readme/basic_sinatra_example.rb

@@ -0,0 +1,128 @@
+#require 'rapitapir' # Only one require needed!
+require 'sinatra/base'
+require_relative '../../lib/rapitapir'
+
+# Simple Book model for demonstration
+class Book
+  attr_reader :id, :title, :author, :published, :isbn, :pages
+  
+  @@books = [
+    { id: 1, title: "The Ruby Programming Language", author: "Matz", published: true, isbn: "978-0596516178", pages: 448 },
+    { id: 2, title: "Effective Ruby", author: "Peter Jones", published: true, isbn: "978-0134045993", pages: 256 },
+    { id: 3, title: "Ruby Under a Microscope", author: "Pat Shaughnessy", published: true, isbn: "978-1593275273", pages: 360 }
+  ]
+  
+  def self.all
+    @@books
+  end
+  
+  def self.find(id)
+    @@books.find { |book| book[:id] == id.to_i }
+  end
+  
+  def self.create(attributes)
+    new_id = (@@books.map { |b| b[:id] }.max || 0) + 1
+    new_book = attributes.merge(id: new_id)
+    @@books << new_book
+    new_book
+  end
+  
+  def self.search(query)
+    results = @@books.select do |book|
+      book[:title].downcase.include?(query.downcase) || 
+      book[:author].downcase.include?(query.downcase)
+    end
+    BookCollection.new(results)
+  end
+  
+  def self.where(conditions)
+    results = @@books.select do |book|
+      conditions.all? { |key, value| book[key] == value }
+    end
+    BookCollection.new(results)
+  end
+end
+
+# Simple collection class to handle chaining
+class BookCollection
+  def initialize(books)
+    @books = books
+  end
+  
+  def limit(count)
+    BookCollection.new(@books.first(count))
+  end
+  
+  def map(&block)
+    @books.map(&block)
+  end
+  
+  def to_a
+    @books
+  end
+end
+
+class BookAPI < SinatraRapiTapir
+  # Configure API information
+  rapitapir do
+    info(
+      title: 'Book API',
+      description: 'A simple book management API',
+      version: '1.0.0'
+    )
+    development_defaults! # Auto CORS, docs, health checks
+  end
+
+  # Define your data schema with T shortcut (globally available!)
+  BOOK_SCHEMA = T.hash({
+    "id" => T.integer,
+    "title" => T.string(min_length: 1, max_length: 255),
+    "author" => T.string(min_length: 1),
+    "published" => T.boolean,
+    "isbn" => T.optional(T.string),
+    "pages" => T.optional(T.integer(minimum: 1))
+  })
+
+  # Define endpoints with the elegant resource DSL and enhanced HTTP verbs
+  api_resource '/books', schema: BOOK_SCHEMA do
+    crud do
+      index { Book.all }
+      
+      show do |inputs|
+        book = Book.find(inputs[:id])
+        halt(404, { error: 'Book not found' }.to_json) unless book
+        book
+      end
+      
+      create do |inputs|
+        Book.create(inputs[:body])
+      end
+    end
+    
+    # Custom endpoint using enhanced DSL
+    custom :get, 'featured' do
+      Book.where(featured: true).to_a
+    end
+  end
+
+  # Alternative endpoint definition using enhanced HTTP verb DSL
+  endpoint(
+    GET('/api/books/search')
+      .query(:q, T.string(min_length: 1), description: 'Search query')
+      .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)), description: 'Results limit')
+      .summary('Search books')
+      .description('Search books by title or author')
+      .tags('Search')
+      .ok(T.array(BOOK_SCHEMA))
+      .bad_request(T.hash({ "error" => T.string }), description: 'Invalid search parameters')
+      .build
+  ) do |inputs|
+    query = inputs[:q]
+    limit = inputs[:limit] || 20
+    
+    books = Book.search(query).limit(limit)
+    books.to_a
+  end
+
+  run! if __FILE__ == $0
+end

data/examples/server/user_api.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/rapitapir'
+
+# Example demonstrating RapiTapir server functionality
+class UserAPI
+  def initialize
+    @adapter = RapiTapir::Server::RackAdapter.new
+    @users = {
+      1 => { id: 1, name: 'John Doe', email: 'john@example.com' },
+      2 => { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+    }
+
+    setup_middleware
+    setup_endpoints
+  end
+
+  def app
+    @adapter
+  end
+
+  private
+
+  def setup_middleware
+    # Add CORS middleware
+    @adapter.use(RapiTapir::Server::Middleware::CORS, {
+                   allow_origin: '*',
+                   allow_methods: %w[GET POST PUT DELETE OPTIONS],
+                   allow_headers: %w[Content-Type Authorization]
+                 })
+
+    # Add logging middleware
+    @adapter.use(RapiTapir::Server::Middleware::Logger)
+  end
+
+  def setup_endpoints
+    setup_list_users
+    setup_get_user
+    setup_create_user
+    setup_update_user
+    setup_delete_user
+  end
+
+  def setup_list_users
+    endpoint = RapiTapir.get('/users')
+                        .summary('List all users')
+                        .description('Returns a list of all users in the system')
+                        .out(RapiTapir::Core::Output.new(kind: :json,
+                                                         type: { users: [{
+                                                           id: :integer, name: :string, email: :string
+                                                         }] }))
+
+    @adapter.register_endpoint(endpoint, method(:list_users))
+  end
+
+  def setup_get_user
+    endpoint = RapiTapir.get('/users/:id')
+                        .summary('Get user by ID')
+                        .description('Returns a single user by their 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(endpoint, method(:get_user))
+  end
+
+  def setup_create_user
+    endpoint = RapiTapir.post('/users')
+                        .summary('Create a new user')
+                        .description('Creates a new user with the provided data')
+                        .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(endpoint, method(:create_user))
+  end
+
+  def setup_update_user
+    endpoint = RapiTapir.put('/users/:id')
+                        .summary('Update an existing user')
+                        .description('Updates an existing user with the provided data')
+                        .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(endpoint, method(:update_user))
+  end
+
+  def setup_delete_user
+    endpoint = RapiTapir.delete('/users/:id')
+                        .summary('Delete a user')
+                        .description('Deletes a user by their ID')
+                        .in(RapiTapir::Core::Input.new(kind: :path, name: :id, type: :integer))
+                        .out(RapiTapir::Core::Output.new(kind: :json, type: { message: :string }))
+
+    @adapter.register_endpoint(endpoint, method(:delete_user))
+  end
+
+  # Handler methods
+  def list_users(_inputs)
+    { users: @users.values }
+  end
+
+  def get_user(inputs)
+    user_id = inputs[:id]
+    user = @users[user_id]
+
+    raise ArgumentError, 'User not found' unless user
+
+    user
+  end
+
+  def create_user(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
+
+  def update_user(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
+
+  def delete_user(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
+
+# Example usage:
+if __FILE__ == $PROGRAM_NAME
+  require 'rack'
+
+  user_api = UserAPI.new
+
+  puts 'Starting RapiTapir User API server on http://localhost:9292'
+  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'
+  puts ''
+  puts 'Example requests:'
+  puts '  curl http://localhost:9292/users'
+  puts '  curl http://localhost:9292/users/1'
+  puts "  curl -X POST http://localhost:9292/users -H 'Content-Type: application/json' " \
+       "-d '{\"name\":\"Bob\",\"email\":\"bob@example.com\"}'"
+
+  Rack::Handler::WEBrick.run(user_api.app, Port: 9292)
+end