rapitapir 0.1.2 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.rubocop.yml +7 -7
- data/.rubocop_todo.yml +88 -0
- data/CHANGELOG.md +29 -1
- data/README.md +1339 -236
- data/RUBY_WEEKLY_LAUNCH_POST.md +200 -0
- data/docs/RAILS_INTEGRATION_IMPLEMENTATION.md +209 -0
- data/docs/SINATRA_EXTENSION.md +399 -348
- data/docs/STRICT_VALIDATION.md +229 -0
- data/docs/VALIDATION_IMPROVEMENTS.md +218 -0
- data/docs/adr/0001-base-class-strategy.md +33 -0
- data/docs/adr/0002-type-shortcut-and-type-system.md +30 -0
- data/docs/adr/0003-openapi-source-of-truth.md +32 -0
- data/docs/adr/0004-client-generation-typescript-first.md +34 -0
- data/docs/adr/0005-auth-architecture.md +32 -0
- data/docs/adr/0006-observability-defaults.md +30 -0
- data/docs/adr/0007-ai-scope-and-boundaries.md +30 -0
- data/docs/adr/README.md +46 -0
- data/docs/adr/template.md +24 -0
- data/docs/ai-integration-plan.md +112 -0
- data/docs/auto-derivation.md +505 -92
- data/docs/blueprint.md +92 -4
- data/docs/endpoint-definition.md +536 -129
- data/docs/implementation-status.md +1 -1
- data/docs/n8n-integration.md +212 -0
- data/docs/observability.md +810 -500
- data/docs/using-mcp.md +93 -0
- data/examples/ai/knowledge_base_rag.rb +83 -0
- data/examples/ai/user_management_mcp.rb +92 -0
- data/examples/ai/user_validation_llm.rb +187 -0
- data/examples/auto_derivation_ruby_friendly.rb +44 -113
- data/examples/cli/user_api_endpoints.rb +63 -36
- data/examples/demo_api.rb +57 -18
- data/examples/enterprise_extension_demo.rb +13 -13
- data/examples/enterprise_rapitapir_api.rb +81 -93
- data/examples/nocodb/nocodb_scaffold/Gemfile +22 -0
- data/examples/nocodb/nocodb_scaffold/README.md +10 -0
- data/examples/nocodb/nocodb_scaffold/Rakefile +7 -0
- data/examples/nocodb/nocodb_scaffold/app/api/app.rb +1139 -0
- data/examples/nocodb/nocodb_scaffold/app/models/email_template.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/faq.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/feature.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/idea.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/itinerary_day.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/route.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/subscriber.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/tour.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/webhook.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models_loader.rb +3 -0
- data/examples/nocodb/nocodb_scaffold/config/database.yml +11 -0
- data/examples/nocodb/nocodb_scaffold/config.ru +9 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152012_create_features.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152013_create_tours.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152014_create_routes.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152015_create_itinerary_days.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152016_create_subscribers.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152017_create_email_templates.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152018_create_faqs.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152019_create_webhooks.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152020_create_ideas.rb +10 -0
- data/examples/nocodb/swagger.json +4378 -0
- data/examples/production_ready_example.rb +78 -58
- data/examples/rails/RAILS_8_GUIDE.md +165 -0
- data/examples/rails/RAILS_LOADING_FIX.rb +35 -0
- data/examples/rails/README.md +497 -0
- data/examples/rails/comprehensive_test.rb +91 -0
- data/examples/rails/config/routes.rb +48 -0
- data/examples/rails/debug_controller.rb +63 -0
- data/examples/rails/detailed_test.rb +46 -0
- data/examples/rails/enhanced_users_controller.rb +278 -0
- data/examples/rails/final_server_test.rb +50 -0
- data/examples/rails/hello_world_app.rb +116 -0
- data/examples/rails/hello_world_controller.rb +186 -0
- data/examples/rails/hello_world_routes.rb +28 -0
- data/examples/rails/rails8_minimal_demo.rb +132 -0
- data/examples/rails/rails8_simple_demo.rb +140 -0
- data/examples/rails/rails8_working_demo.rb +255 -0
- data/examples/rails/real_world_blog_api.rb +510 -0
- data/examples/rails/server_test.rb +46 -0
- data/examples/rails/test_direct_processing.rb +41 -0
- data/examples/rails/test_hello_world.rb +80 -0
- data/examples/rails/test_rails_integration.rb +54 -0
- data/examples/rails/traditional_app/Gemfile +37 -0
- data/examples/rails/traditional_app/README.md +265 -0
- data/examples/rails/traditional_app/app/controllers/api/v1/posts_controller.rb +254 -0
- data/examples/rails/traditional_app/app/controllers/api/v1/users_controller.rb +220 -0
- data/examples/rails/traditional_app/app/controllers/application_controller.rb +86 -0
- data/examples/rails/traditional_app/app/controllers/application_controller_simplified.rb +87 -0
- data/examples/rails/traditional_app/app/controllers/documentation_controller.rb +149 -0
- data/examples/rails/traditional_app/app/controllers/health_controller.rb +42 -0
- data/examples/rails/traditional_app/config/routes.rb +25 -0
- data/examples/rails/traditional_app/config/routes_best_practice.rb +25 -0
- data/examples/rails/traditional_app/config/routes_simplified.rb +36 -0
- data/examples/rails/traditional_app_runnable.rb +406 -0
- data/examples/rails/users_controller.rb +4 -1
- data/examples/serverless/Gemfile +43 -0
- data/examples/serverless/QUICKSTART.md +331 -0
- data/examples/serverless/README.md +520 -0
- data/examples/serverless/aws_lambda_example.rb +307 -0
- data/examples/serverless/aws_sam_template.yaml +215 -0
- data/examples/serverless/azure_functions_example.rb +407 -0
- data/examples/serverless/deploy.rb +204 -0
- data/examples/serverless/gcp_cloud_functions_example.rb +367 -0
- data/examples/serverless/gcp_function.yaml +23 -0
- data/examples/serverless/host.json +24 -0
- data/examples/serverless/package.json +32 -0
- data/examples/serverless/spec/aws_lambda_spec.rb +196 -0
- data/examples/serverless/spec/spec_helper.rb +89 -0
- data/examples/serverless/vercel.json +31 -0
- data/examples/serverless/vercel_example.rb +404 -0
- data/examples/simple_demo_api.rb +40 -7
- data/examples/strict_validation_examples.rb +104 -0
- data/examples/user_api.rb +130 -132
- data/examples/validation_error_examples.rb +173 -0
- data/lib/rapitapir/ai/llm_instruction.rb +456 -0
- data/lib/rapitapir/ai/mcp.rb +134 -0
- data/lib/rapitapir/ai/rag.rb +287 -0
- data/lib/rapitapir/ai/rag_middleware.rb +147 -0
- data/lib/rapitapir/auth/oauth2.rb +44 -58
- data/lib/rapitapir/cli/command.rb +392 -6
- data/lib/rapitapir/cli/mcp_export.rb +18 -0
- data/lib/rapitapir/cli/scaffold_generator.rb +639 -0
- data/lib/rapitapir/cli/validator.rb +3 -7
- data/lib/rapitapir/core/endpoint.rb +59 -6
- data/lib/rapitapir/core/enhanced_endpoint.rb +3 -7
- data/lib/rapitapir/dsl/enhanced_structures.rb +1 -1
- data/lib/rapitapir/dsl/fluent_endpoint_builder.rb +53 -0
- data/lib/rapitapir/endpoint_registry.rb +47 -0
- data/lib/rapitapir/observability/health_check.rb +4 -4
- data/lib/rapitapir/observability/logging.rb +10 -10
- data/lib/rapitapir/openapi/schema_generator.rb +46 -2
- data/lib/rapitapir/schema.rb +2 -2
- data/lib/rapitapir/server/enhanced_rack_adapter.rb +11 -8
- data/lib/rapitapir/server/middleware.rb +2 -2
- data/lib/rapitapir/server/rack_adapter.rb +1 -3
- data/lib/rapitapir/server/rails/configuration.rb +77 -0
- data/lib/rapitapir/server/rails/controller_base.rb +185 -0
- data/lib/rapitapir/server/rails/documentation_helpers.rb +76 -0
- data/lib/rapitapir/server/rails/resource_builder.rb +181 -0
- data/lib/rapitapir/server/rails/routes.rb +114 -0
- data/lib/rapitapir/server/rails_adapter.rb +10 -3
- data/lib/rapitapir/server/rails_adapter_class.rb +1 -3
- data/lib/rapitapir/server/rails_controller.rb +1 -3
- data/lib/rapitapir/server/rails_integration.rb +67 -0
- data/lib/rapitapir/server/rails_response_handler.rb +16 -3
- data/lib/rapitapir/server/sinatra_adapter.rb +29 -5
- data/lib/rapitapir/server/sinatra_integration.rb +4 -4
- data/lib/rapitapir/sinatra/extension.rb +2 -2
- data/lib/rapitapir/sinatra/oauth2_helpers.rb +34 -40
- data/lib/rapitapir/types/array.rb +4 -0
- data/lib/rapitapir/types/auto_derivation.rb +4 -20
- data/lib/rapitapir/types/datetime.rb +1 -3
- data/lib/rapitapir/types/float.rb +2 -6
- data/lib/rapitapir/types/hash.rb +40 -2
- data/lib/rapitapir/types/integer.rb +4 -12
- data/lib/rapitapir/types/object.rb +6 -2
- data/lib/rapitapir/types.rb +6 -2
- data/lib/rapitapir/version.rb +1 -1
- data/lib/rapitapir.rb +5 -3
- data/rapitapir.gemspec +3 -2
- metadata +142 -8
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# 🦙 Introducing RapiTapir: Type-Safe HTTP APIs for Ruby
|
|
2
|
+
|
|
3
|
+
TL;DR: RapiTapir brings Tapir-style, declarative, type-safe APIs to Ruby with a clean DSL, automatic OpenAPI docs, a TypeScript client, and a new one-command scaffold from an OpenAPI spec.
|
|
4
|
+
|
|
5
|
+
## The Problem: Ruby API Development Pain Points
|
|
6
|
+
|
|
7
|
+
Ruby developers love the language's expressiveness, but API development often involves:
|
|
8
|
+
|
|
9
|
+
- **Manual documentation** that gets out of sync with code
|
|
10
|
+
- **Runtime errors** from type mismatches that could be caught earlier
|
|
11
|
+
- **Boilerplate code** for validation, serialization, and error handling
|
|
12
|
+
- **Inconsistent patterns** across different teams and projects
|
|
13
|
+
|
|
14
|
+
What if we could have the type safety of languages like Scala while keeping Ruby's elegance?
|
|
15
|
+
|
|
16
|
+
## Enter RapiTapir 🦙
|
|
17
|
+
|
|
18
|
+
RapiTapir is inspired by [Scala's Tapir](https://github.com/softwaremill/tapir), bringing **declarative, type-safe API development** to Ruby. Define your endpoints once with strong typing, and get automatic validation, documentation, and client generation.
|
|
19
|
+
|
|
20
|
+
### The Magic: Clean Base Class Syntax
|
|
21
|
+
|
|
22
|
+
```ruby
|
|
23
|
+
require 'rapitapir'
|
|
24
|
+
|
|
25
|
+
class BookAPI < RapiTapir::SinatraRapiTapir
|
|
26
|
+
rapitapir do
|
|
27
|
+
info(title: 'Book API', version: '1.0.0')
|
|
28
|
+
development_defaults! # health checks, CORS, docs
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
# T shortcut available globally
|
|
32
|
+
BOOK_SCHEMA = T.hash({
|
|
33
|
+
"id" => T.integer,
|
|
34
|
+
"title" => T.string(min_length: 1, max_length: 255),
|
|
35
|
+
"author" => T.string(min_length: 1),
|
|
36
|
+
"published" => T.boolean,
|
|
37
|
+
"isbn" => T.optional(T.string),
|
|
38
|
+
"pages" => T.optional(T.integer(minimum: 1))
|
|
39
|
+
})
|
|
40
|
+
|
|
41
|
+
endpoint(
|
|
42
|
+
GET('/books')
|
|
43
|
+
.query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)))
|
|
44
|
+
.query(:genre, T.optional(T.string))
|
|
45
|
+
.summary('List books with filtering')
|
|
46
|
+
.ok(T.array(BOOK_SCHEMA))
|
|
47
|
+
.build
|
|
48
|
+
) do |inputs|
|
|
49
|
+
Book.where(genre: inputs[:genre])
|
|
50
|
+
.limit(inputs[:limit] || 20)
|
|
51
|
+
.map(&:to_h)
|
|
52
|
+
end
|
|
53
|
+
end
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Start the server and visit `http://localhost:4567/docs` for **interactive Swagger documentation** that's always in sync with your code.
|
|
57
|
+
|
|
58
|
+
## Why RapiTapir Feels Like Ruby Magic ✨
|
|
59
|
+
|
|
60
|
+
### 1. **Zero Boilerplate Setup**
|
|
61
|
+
```ruby
|
|
62
|
+
# One line to get a complete API server
|
|
63
|
+
class MyAPI < SinatraRapiTapir
|
|
64
|
+
# Enhanced HTTP verbs automatically available
|
|
65
|
+
# T shortcut for types works everywhere
|
|
66
|
+
# Health checks, CORS, docs - all included
|
|
67
|
+
end
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### 2. **Type Safety Without Ceremony**
|
|
71
|
+
```ruby
|
|
72
|
+
# Define once, use everywhere
|
|
73
|
+
USER_SCHEMA = T.hash({
|
|
74
|
+
"email" => T.email, # built-in email validation
|
|
75
|
+
"age" => T.optional(T.integer(minimum: 0, maximum: 150))
|
|
76
|
+
})
|
|
77
|
+
|
|
78
|
+
# Automatic validation + coercion
|
|
79
|
+
endpoint(POST('/users').json_body(USER_SCHEMA).build) do |inputs|
|
|
80
|
+
User.create(inputs[:body])
|
|
81
|
+
end
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### 3. **RESTful Resources Made Simple**
|
|
85
|
+
```ruby
|
|
86
|
+
# Complete CRUD API in ~10 lines
|
|
87
|
+
api_resource '/books', schema: BOOK_SCHEMA do
|
|
88
|
+
crud do
|
|
89
|
+
index { Book.all }
|
|
90
|
+
show { |inputs| Book.find(inputs[:id]) }
|
|
91
|
+
create { |inputs| Book.create(inputs[:body]) }
|
|
92
|
+
update { |inputs| Book.update(inputs[:id], inputs[:body]) }
|
|
93
|
+
destroy { |inputs| Book.destroy(inputs[:id]); status 204 }
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
# Add custom endpoints with full type safety
|
|
97
|
+
custom :get, 'featured' do
|
|
98
|
+
Book.where(featured: true)
|
|
99
|
+
end
|
|
100
|
+
end
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## From OpenAPI to Running App (Scaffold)
|
|
104
|
+
|
|
105
|
+
Input: an OpenAPI/Swagger JSON.
|
|
106
|
+
|
|
107
|
+
Output: a runnable SinatraRapiTapir + ActiveRecord + SQLite app with:
|
|
108
|
+
- config.ru, Rakefile, Gemfile
|
|
109
|
+
- app/api/app.rb (endpoints mapped; docs, tags, descriptions, and security reflected)
|
|
110
|
+
- app/models, db/migrate, config/database.yml
|
|
111
|
+
- health check and docs enabled by default
|
|
112
|
+
|
|
113
|
+
Try it:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
rapitapir generate scaffold --from openapi.json --out ./my_api
|
|
117
|
+
cd my_api
|
|
118
|
+
bundle install
|
|
119
|
+
bundle exec rake db:create db:migrate
|
|
120
|
+
bundle exec rackup
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Production-Ready Features 🛡️
|
|
124
|
+
|
|
125
|
+
- Development defaults: health checks, CORS, and docs out of the box.
|
|
126
|
+
- Security headers: header-based API keys in your OpenAPI are scaffolded and reflected in docs.
|
|
127
|
+
- Observability: health endpoint enabled; metrics/tracing integration planned.
|
|
128
|
+
|
|
129
|
+
## Real-World Benefits
|
|
130
|
+
|
|
131
|
+
**🚀 Development Speed**: Define endpoints declaratively, get validation + docs for free
|
|
132
|
+
|
|
133
|
+
**🐛 Fewer Bugs**: Type checking catches issues at definition time, not runtime
|
|
134
|
+
|
|
135
|
+
**📖 Always-Current Docs**: Swagger UI generated from your actual code
|
|
136
|
+
|
|
137
|
+
**🔧 Better DX**: Enhanced error messages, auto-completion, consistent patterns
|
|
138
|
+
|
|
139
|
+
**⚡ Easy Testing**: Validate schemas independently, generate test fixtures
|
|
140
|
+
|
|
141
|
+
## Framework Integration
|
|
142
|
+
|
|
143
|
+
Works with your existing Ruby stack:
|
|
144
|
+
|
|
145
|
+
```ruby
|
|
146
|
+
# Sinatra (recommended) - clean inheritance
|
|
147
|
+
class API < RapiTapir::SinatraRapiTapir; end
|
|
148
|
+
|
|
149
|
+
# Sinatra extension
|
|
150
|
+
register RapiTapir::Sinatra::Extension
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## The Ruby Community Connection
|
|
154
|
+
|
|
155
|
+
RapiTapir builds on Ruby's strengths:
|
|
156
|
+
|
|
157
|
+
- **Sinatra's simplicity** with enhanced capabilities
|
|
158
|
+
- **Rack's composability** for middleware and deployment
|
|
159
|
+
- **Ruby's expressiveness** with added type safety
|
|
160
|
+
- **Community gems** for auth, testing, deployment
|
|
161
|
+
|
|
162
|
+
It's not about replacing your stack - it's about making it better.
|
|
163
|
+
|
|
164
|
+
## Getting Started
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
gem install rapitapir
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Or add to your Gemfile:
|
|
171
|
+
```ruby
|
|
172
|
+
gem 'rapitapir'
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Check out the examples and docs:
|
|
176
|
+
- Examples: https://github.com/riccardomerolla/rapitapir/tree/main/examples
|
|
177
|
+
- Docs: https://riccardomerolla.github.io/rapitapir
|
|
178
|
+
|
|
179
|
+
## What’s Next?
|
|
180
|
+
|
|
181
|
+
- Rails integration for seamless adoption in existing apps
|
|
182
|
+
- More client generators (Python, Go)
|
|
183
|
+
- Enhanced observability and tracing
|
|
184
|
+
- Plugin ecosystem for community extensions
|
|
185
|
+
|
|
186
|
+
## Try It Today
|
|
187
|
+
|
|
188
|
+
RapiTapir is **production-ready** with comprehensive tests, clear documentation, and real-world examples. Whether you're building a new API or enhancing an existing one, RapiTapir helps you write better Ruby code.
|
|
189
|
+
|
|
190
|
+
**Links:**
|
|
191
|
+
- Gem: https://rubygems.org/gems/rapitapir
|
|
192
|
+
- Homepage: https://riccardomerolla.github.io/rapitapir
|
|
193
|
+
- Source: https://github.com/riccardomerolla/rapitapir
|
|
194
|
+
- Docs: https://github.com/riccardomerolla/rapitapir/tree/main/examples
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
*Built with ❤️ for the Ruby community. Questions? Feedback? Open an issue or discussion on GitHub!*
|
|
199
|
+
|
|
200
|
+
**RapiTapir** - APIs so clean and fast, they practically run wild! 🦙⚡
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
# Enhanced Rails Integration Implementation Summary
|
|
2
|
+
|
|
3
|
+
## 🎯 **Implementation Complete: Phase 1**
|
|
4
|
+
|
|
5
|
+
We have successfully implemented **Phase 1** of the enhanced Rails integration plan, delivering a **Sinatra-like developer experience** for Rails controllers.
|
|
6
|
+
|
|
7
|
+
## ✅ **What We Built**
|
|
8
|
+
|
|
9
|
+
### 1. **Enhanced Rails Controller Base Class**
|
|
10
|
+
- **File**: `lib/rapitapir/server/rails/controller_base.rb`
|
|
11
|
+
- **Features**:
|
|
12
|
+
- Clean inheritance: `class MyController < RapiTapir::Server::Rails::ControllerBase`
|
|
13
|
+
- `rapitapir` configuration block (same as Sinatra)
|
|
14
|
+
- `T` shortcut automatically available
|
|
15
|
+
- Enhanced HTTP verb DSL (`GET()`, `POST()`, etc.)
|
|
16
|
+
- Automatic action generation
|
|
17
|
+
- `endpoint()` method with auto Rails action creation
|
|
18
|
+
- `api_resource()` method for CRUD operations
|
|
19
|
+
|
|
20
|
+
### 2. **Rails Resource Builder**
|
|
21
|
+
- **File**: `lib/rapitapir/server/rails/resource_builder.rb`
|
|
22
|
+
- **Features**:
|
|
23
|
+
- `api_resource '/path', schema: SCHEMA do ... end`
|
|
24
|
+
- `crud` block with `index`, `show`, `create`, `update`, `destroy`
|
|
25
|
+
- `custom` method for additional endpoints
|
|
26
|
+
- Automatic pagination parameters
|
|
27
|
+
- Standard error responses
|
|
28
|
+
- Same API as Sinatra's ResourceBuilder
|
|
29
|
+
|
|
30
|
+
### 3. **Auto Route Generation**
|
|
31
|
+
- **File**: `lib/rapitapir/server/rails/routes.rb`
|
|
32
|
+
- **Features**:
|
|
33
|
+
- `rapitapir_routes_for(ControllerClass)`
|
|
34
|
+
- `rapitapir_auto_routes` (auto-discover all controllers)
|
|
35
|
+
- Converts RapiTapir paths to Rails routes
|
|
36
|
+
- RESTful route naming conventions
|
|
37
|
+
|
|
38
|
+
### 4. **Complete Examples**
|
|
39
|
+
- **Enhanced Controller**: `examples/rails/enhanced_users_controller.rb`
|
|
40
|
+
- **Legacy Comparison**: `examples/rails/users_controller.rb` (marked as legacy)
|
|
41
|
+
- **Routes Config**: `examples/rails/config/routes.rb`
|
|
42
|
+
- **Documentation**: `examples/rails/README.md`
|
|
43
|
+
|
|
44
|
+
### 5. **Comprehensive Tests**
|
|
45
|
+
- **File**: `spec/server/rails/enhanced_integration_spec.rb`
|
|
46
|
+
- **Coverage**: ControllerBase, ResourceBuilder, Routes module
|
|
47
|
+
|
|
48
|
+
## 🚀 **Developer Experience Achieved**
|
|
49
|
+
|
|
50
|
+
### **Before (Verbose Legacy Approach)**
|
|
51
|
+
```ruby
|
|
52
|
+
class UsersController < ApplicationController
|
|
53
|
+
include RapiTapir::Server::Rails::Controller
|
|
54
|
+
|
|
55
|
+
rapitapir_endpoint :index, RapiTapir.get('/users')
|
|
56
|
+
.summary('List users')
|
|
57
|
+
.out(RapiTapir::Core::Output.new(
|
|
58
|
+
kind: :json, type: { users: Array }
|
|
59
|
+
)) do |_inputs|
|
|
60
|
+
{ users: @users.values }
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
def index
|
|
64
|
+
process_rapitapir_endpoint
|
|
65
|
+
end
|
|
66
|
+
end
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### **After (Clean Enhanced Approach)**
|
|
70
|
+
```ruby
|
|
71
|
+
class UsersController < RapiTapir::Server::Rails::ControllerBase
|
|
72
|
+
rapitapir do
|
|
73
|
+
info(title: 'Users API', version: '1.0.0')
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
USER_SCHEMA = T.hash({
|
|
77
|
+
"id" => T.integer,
|
|
78
|
+
"name" => T.string,
|
|
79
|
+
"email" => T.email
|
|
80
|
+
})
|
|
81
|
+
|
|
82
|
+
api_resource '/users', schema: USER_SCHEMA do
|
|
83
|
+
crud do
|
|
84
|
+
index { User.all.map(&:attributes) }
|
|
85
|
+
end
|
|
86
|
+
end
|
|
87
|
+
end
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## 📊 **Feature Parity with Sinatra**
|
|
91
|
+
|
|
92
|
+
| Feature | Sinatra | Enhanced Rails | Status |
|
|
93
|
+
|---------|---------|----------------|---------|
|
|
94
|
+
| **Clean Inheritance** | ✅ `< SinatraRapiTapir` | ✅ `< ControllerBase` | **✅ COMPLETE** |
|
|
95
|
+
| **Configuration Block** | ✅ `rapitapir do...end` | ✅ `rapitapir do...end` | **✅ COMPLETE** |
|
|
96
|
+
| **HTTP Verb DSL** | ✅ `GET()`, `POST()` | ✅ `GET()`, `POST()` | **✅ COMPLETE** |
|
|
97
|
+
| **T Shortcuts** | ✅ `T.string` | ✅ `T.string` | **✅ COMPLETE** |
|
|
98
|
+
| **Resource Builder** | ✅ `api_resource` | ✅ `api_resource` | **✅ COMPLETE** |
|
|
99
|
+
| **CRUD Operations** | ✅ `crud do...end` | ✅ `crud do...end` | **✅ COMPLETE** |
|
|
100
|
+
| **Custom Endpoints** | ✅ `custom :get, 'path'` | ✅ `custom :get, 'path'` | **✅ COMPLETE** |
|
|
101
|
+
| **Auto Actions** | ✅ Automatic | ✅ Automatic | **✅ COMPLETE** |
|
|
102
|
+
| **Auto Routes** | ✅ Built-in | ✅ `rapitapir_auto_routes` | **✅ COMPLETE** |
|
|
103
|
+
|
|
104
|
+
## 🎉 **Key Achievements**
|
|
105
|
+
|
|
106
|
+
### **1. Developer Experience Gap Eliminated**
|
|
107
|
+
Rails developers now enjoy the **same clean, elegant syntax** as Sinatra developers.
|
|
108
|
+
|
|
109
|
+
### **2. Zero Boilerplate**
|
|
110
|
+
- No manual `def action; process_rapitapir_endpoint; end`
|
|
111
|
+
- No verbose `RapiTapir::Core::Input/Output` objects
|
|
112
|
+
- No manual route definitions
|
|
113
|
+
|
|
114
|
+
### **3. Automatic Everything**
|
|
115
|
+
- **Actions**: Generated automatically from endpoints
|
|
116
|
+
- **Routes**: Auto-generated with `rapitapir_auto_routes`
|
|
117
|
+
- **Type Safety**: Full validation and error handling
|
|
118
|
+
|
|
119
|
+
### **4. Rails Integration**
|
|
120
|
+
- Works with Rails conventions
|
|
121
|
+
- Access to Rails helpers (`params`, `render`, `head`)
|
|
122
|
+
- Compatible with Rails middleware and filters
|
|
123
|
+
|
|
124
|
+
## 🔄 **Next Steps (Future Phases)**
|
|
125
|
+
|
|
126
|
+
### **Phase 2: Documentation & Features** (Next)
|
|
127
|
+
- Auto-generated `/docs` endpoint for Rails
|
|
128
|
+
- Development defaults (`CORS`, health checks)
|
|
129
|
+
- OpenAPI JSON endpoint
|
|
130
|
+
|
|
131
|
+
### **Phase 3: Production Features** (Later)
|
|
132
|
+
- Authentication helpers
|
|
133
|
+
- Observability integration
|
|
134
|
+
- Rate limiting
|
|
135
|
+
- Security headers
|
|
136
|
+
|
|
137
|
+
### **Phase 4: Developer Tools** (Later)
|
|
138
|
+
- Rails generator: `rails generate rapitapir:controller Users`
|
|
139
|
+
- Schema auto-derivation from ActiveRecord models
|
|
140
|
+
- Migration tools
|
|
141
|
+
|
|
142
|
+
## 📁 **File Structure**
|
|
143
|
+
|
|
144
|
+
```
|
|
145
|
+
lib/rapitapir/server/rails/
|
|
146
|
+
├── controller_base.rb # ✅ Main base class
|
|
147
|
+
├── resource_builder.rb # ✅ CRUD operations
|
|
148
|
+
└── routes.rb # ✅ Auto route generation
|
|
149
|
+
|
|
150
|
+
examples/rails/
|
|
151
|
+
├── enhanced_users_controller.rb # ✅ New approach example
|
|
152
|
+
├── users_controller.rb # ✅ Legacy example (marked)
|
|
153
|
+
├── config/
|
|
154
|
+
│ └── routes.rb # ✅ Routes configuration
|
|
155
|
+
└── README.md # ✅ Complete documentation
|
|
156
|
+
|
|
157
|
+
spec/server/rails/
|
|
158
|
+
└── enhanced_integration_spec.rb # ✅ Comprehensive tests
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## 🎯 **Usage Summary**
|
|
162
|
+
|
|
163
|
+
### **1. Create Enhanced Controller**
|
|
164
|
+
```ruby
|
|
165
|
+
class BooksController < RapiTapir::Server::Rails::ControllerBase
|
|
166
|
+
rapitapir do
|
|
167
|
+
info(title: 'Books API', version: '1.0.0')
|
|
168
|
+
end
|
|
169
|
+
|
|
170
|
+
BOOK_SCHEMA = T.hash({
|
|
171
|
+
"id" => T.integer,
|
|
172
|
+
"title" => T.string,
|
|
173
|
+
"author" => T.string
|
|
174
|
+
})
|
|
175
|
+
|
|
176
|
+
api_resource '/books', schema: BOOK_SCHEMA do
|
|
177
|
+
crud do
|
|
178
|
+
index { Book.all.map(&:attributes) }
|
|
179
|
+
show { |inputs| Book.find(inputs[:id]).attributes }
|
|
180
|
+
create { |inputs| Book.create!(inputs[:body]).attributes }
|
|
181
|
+
end
|
|
182
|
+
end
|
|
183
|
+
end
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### **2. Auto-Generate Routes**
|
|
187
|
+
```ruby
|
|
188
|
+
# config/routes.rb
|
|
189
|
+
Rails.application.routes.draw do
|
|
190
|
+
rapitapir_auto_routes
|
|
191
|
+
end
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### **3. That's It!**
|
|
195
|
+
- Fully functional API with type safety
|
|
196
|
+
- Automatic validation and error handling
|
|
197
|
+
- Auto-generated routes
|
|
198
|
+
- Ready for production use
|
|
199
|
+
|
|
200
|
+
## 🎊 **Success Metrics**
|
|
201
|
+
|
|
202
|
+
- ✅ **Lines of Code**: Reduced from ~50 lines to ~15 lines for basic CRUD
|
|
203
|
+
- ✅ **Boilerplate**: Eliminated 100% of manual action definitions
|
|
204
|
+
- ✅ **Type Safety**: Maintained full validation and error handling
|
|
205
|
+
- ✅ **Rails Compatibility**: Works seamlessly with Rails conventions
|
|
206
|
+
- ✅ **Feature Parity**: Achieved 100% parity with Sinatra DSL
|
|
207
|
+
- ✅ **Developer Experience**: Identical elegant syntax across frameworks
|
|
208
|
+
|
|
209
|
+
**🎯 Mission Accomplished: Rails integration now matches Sinatra's elegance!**
|