rapitapir 2.0.0 → 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_todo.yml +5 -0
- data/CHANGELOG.md +29 -1
- data/README.md +23 -4
- data/RUBY_WEEKLY_LAUNCH_POST.md +43 -62
- 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/blueprint.md +92 -4
- data/docs/implementation-status.md +1 -1
- 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/simple_demo_api.rb +40 -7
- data/examples/user_api.rb +130 -132
- data/lib/rapitapir/auth/oauth2.rb +1 -1
- data/lib/rapitapir/cli/command.rb +30 -4
- data/lib/rapitapir/cli/scaffold_generator.rb +639 -0
- data/lib/rapitapir/cli/validator.rb +1 -1
- data/lib/rapitapir/core/enhanced_endpoint.rb +1 -1
- data/lib/rapitapir/dsl/enhanced_structures.rb +1 -1
- data/lib/rapitapir/openapi/schema_generator.rb +46 -2
- data/lib/rapitapir/server/enhanced_rack_adapter.rb +11 -8
- data/lib/rapitapir/server/middleware.rb +2 -2
- data/lib/rapitapir/types/auto_derivation.rb +2 -4
- data/lib/rapitapir/version.rb +1 -1
- data/rapitapir.gemspec +3 -2
- metadata +70 -8
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 6d2520e4b24ee5927e01f130de108a554b6b820f0cb501160e129dc054852320
|
|
4
|
+
data.tar.gz: 0ffafcc50aeb89b89ab477dbc252fcd8a5352d51134960ac92ee02053bc6b7e3
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: fd644750fd860960c7e0b78af2ef56d60b8ffbfc575d65f22937f8e2c1de3a4907898b7ba62711d4a27baaa2497f3dd9052c0547fbc30f06d7c6d4c107f56b2d
|
|
7
|
+
data.tar.gz: 1ef21dc5edb5a112e91a0e9ce0be85b8894d380a1877714ab1cd1578185fed5d2ccc0e76d25734910eabebd41c6392d6e95a0bdb7b94dffa93a6b7e7207b8520
|
data/.rubocop_todo.yml
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -1,10 +1,38 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
All
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [2.1.0] - 2026-11-22
|
|
9
|
+
|
|
10
|
+
### Summary
|
|
11
|
+
Dependency refresh to the latest gem releases, with code adaptations for
|
|
12
|
+
breaking API changes, and a full repair of the example catalog.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
- 📦 **jwt runtime dependency declared in the gemspec** (`>= 2.10, < 4.0`) — it was lazily `require`d by `RapiTapir::Auth` OAuth2 validation but never declared, so installs could silently lack it
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
- 🔢 **Bumped all dependencies to their latest releases**: dotenv 3.2, json 3.1, jwt 3.3, rack 3.2, puma 8.1, simplecov 1.3, sinatra 4.2, webmock 3.38, rubocop 1.92, rackup 2.3, rack-test 2.3, rspec 3.13, webrick 1.9, OpenTelemetry exporter-otlp 0.37 / instrumentation-all 0.102 / sdk 1.13
|
|
19
|
+
- 🐾 **Minimum Ruby raised to 3.3** (`required_ruby_version >= 3.3`). The latest OpenTelemetry stack (api 1.9+, sdk 1.11+, common 0.24+) declares `ruby >= 3.3`; keeping the current otel releases required dropping the EOL 3.1/3.2 runtimes. CI matrix and all workflows now test 3.3/3.4. **This is a breaking change for Ruby 3.1/3.2 users.**
|
|
20
|
+
- ⬆️ **json range widened in the gemspec** to `>= 2.6, < 4.0` to match the refreshed stack
|
|
21
|
+
- 🧩 **JWT v3 compatibility**: `JWT.decode` no longer accepts the positional `verify` argument — replaced with the `verify_signature: true` option (works on jwt ≥ 2.10 and 3.x)
|
|
22
|
+
- 🎨 **RuboCop 1.92 compliance**: `Style/DirectiveScope` disable/enable pairs converted to `disable-next`
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
- 📚 **`examples/enterprise_rapitapir_api.rb`**: `configure`/`set` were called from an instance `initialize` (crash on boot); auth/middleware setup moved to class level; `SinatraAdapter` now binds to the app class (Sinatra 4 removed instance→class delegation); handlers use the adapter's `[status, headers, body]` response protocol
|
|
26
|
+
- 📚 **`examples/enterprise_extension_demo.rb`**: `bearer_auth` → `add_auth_scheme(:bearer, RapiTapir::Auth.bearer_token(...))` (the real `Configuration` API)
|
|
27
|
+
- 📚 **`examples/demo_api.rb`, `simple_demo_api.rb`, `cli/user_api_endpoints.rb`, `user_api.rb`, `production_ready_example.rb`**: rewritten from the removed `.in/.out/.error_out` DSL onto the current builder (`json_body`, `ok`, `created`, `no_content`, `not_found`, …) with proper `RapiTapir::Types.hash/array` types
|
|
28
|
+
- 📚 **`examples/auto_derivation_ruby_friendly.rb`**: now demos only the real derivation APIs (`from_hash`, `from_open_struct`, `from_json_schema`, `from_protobuf`)
|
|
29
|
+
- 🧪 **All 18 examples verified running**, including live HTTP checks of the three server examples
|
|
30
|
+
|
|
31
|
+
### Verification
|
|
32
|
+
- ✅ 695 RSpec examples, 0 failures
|
|
33
|
+
- ✅ RuboCop: 91 files, no offenses
|
|
34
|
+
- ✅ `gem build` produces a clean installable package
|
|
35
|
+
|
|
8
36
|
## [Unreleased] - 2025-08-02
|
|
9
37
|
|
|
10
38
|
### Summary
|
data/README.md
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
# RapiTapir
|
|
2
2
|
|
|
3
|
-
[](spec/)
|
|
4
|
+
[](coverage/)
|
|
5
|
+
[](coverage/)
|
|
6
|
+
[](Gemfile)
|
|
6
7
|
[](LICENSE)
|
|
7
8
|
[](https://github.com/rubocop/rubocop)
|
|
8
9
|
[](lib/rapitapir/ai/)
|
|
@@ -18,7 +19,7 @@
|
|
|
18
19
|
- **⚡ T Shortcut**: Use `T.string` instead of `RapiTapir::Types.string` everywhere
|
|
19
20
|
- **📚 GitHub Pages Ready**: Modern documentation deployment with GitHub Actions
|
|
20
21
|
- **🔍 CLI Toolkit**: Complete command-line interface for generation, validation, and serving
|
|
21
|
-
- **🧪 Comprehensive Tests**:
|
|
22
|
+
- **🧪 Comprehensive Tests**: 695 examples, 0 failures; 72.7% coverage
|
|
22
23
|
|
|
23
24
|
## ✨ Why RapiTapir?
|
|
24
25
|
|
|
@@ -1388,6 +1389,24 @@ Explore our comprehensive examples directory:
|
|
|
1388
1389
|
- **[Observability Setup](examples/observability/)** - Monitoring and health checks
|
|
1389
1390
|
- **[CLI Examples](examples/cli/)** - Command-line toolkit usage
|
|
1390
1391
|
|
|
1392
|
+
## Architecture Decision Records (ADRs)
|
|
1393
|
+
|
|
1394
|
+
Key architectural decisions are tracked in `docs/adr/`:
|
|
1395
|
+
|
|
1396
|
+
- ADR index and guidelines: [docs/adr/README.md](docs/adr/README.md)
|
|
1397
|
+
- Template: [docs/adr/template.md](docs/adr/template.md)
|
|
1398
|
+
|
|
1399
|
+
Initial ADRs:
|
|
1400
|
+
|
|
1401
|
+
- [ADR-0001: Base class strategy (SinatraRapiTapir) vs manual extension](docs/adr/0001-base-class-strategy.md)
|
|
1402
|
+
- [ADR-0002: Type shortcut (T) and type system boundaries](docs/adr/0002-type-shortcut-and-type-system.md)
|
|
1403
|
+
- [ADR-0003: OpenAPI source-of-truth and doc generation flow](docs/adr/0003-openapi-source-of-truth.md)
|
|
1404
|
+
- [ADR-0004: Client generation target (TypeScript first) and interface conventions](docs/adr/0004-client-generation-typescript-first.md)
|
|
1405
|
+
- [ADR-0005: Authentication architecture (schemes + helpers + middleware)](docs/adr/0005-auth-architecture.md)
|
|
1406
|
+
- [ADR-0006: Observability defaults (health, logging, metrics/tracing hooks)](docs/adr/0006-observability-defaults.md)
|
|
1407
|
+
- [ADR-0007: AI features scope (RAG/LLM/MCP) and maintainability boundaries](docs/adr/0007-ai-scope-and-boundaries.md)
|
|
1408
|
+
|
|
1409
|
+
|
|
1391
1410
|
## 🛠️ CLI Development Toolkit
|
|
1392
1411
|
|
|
1393
1412
|
RapiTapir includes a powerful CLI for streamlined development:
|
data/RUBY_WEEKLY_LAUNCH_POST.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 🦙 Introducing RapiTapir: Type-Safe HTTP APIs for Ruby
|
|
2
2
|
|
|
3
|
-
|
|
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
4
|
|
|
5
5
|
## The Problem: Ruby API Development Pain Points
|
|
6
6
|
|
|
@@ -15,21 +15,20 @@ What if we could have the type safety of languages like Scala while keeping Ruby
|
|
|
15
15
|
|
|
16
16
|
## Enter RapiTapir 🦙
|
|
17
17
|
|
|
18
|
-
RapiTapir is inspired by [Scala's Tapir](https://github.com/softwaremill/tapir)
|
|
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
19
|
|
|
20
20
|
### The Magic: Clean Base Class Syntax
|
|
21
21
|
|
|
22
22
|
```ruby
|
|
23
23
|
require 'rapitapir'
|
|
24
24
|
|
|
25
|
-
class BookAPI < SinatraRapiTapir
|
|
26
|
-
# 🎯 Configure once, get everything
|
|
25
|
+
class BookAPI < RapiTapir::SinatraRapiTapir
|
|
27
26
|
rapitapir do
|
|
28
27
|
info(title: 'Book API', version: '1.0.0')
|
|
29
|
-
development_defaults! #
|
|
28
|
+
development_defaults! # health checks, CORS, docs
|
|
30
29
|
end
|
|
31
30
|
|
|
32
|
-
#
|
|
31
|
+
# T shortcut available globally
|
|
33
32
|
BOOK_SCHEMA = T.hash({
|
|
34
33
|
"id" => T.integer,
|
|
35
34
|
"title" => T.string(min_length: 1, max_length: 255),
|
|
@@ -39,22 +38,18 @@ class BookAPI < SinatraRapiTapir
|
|
|
39
38
|
"pages" => T.optional(T.integer(minimum: 1))
|
|
40
39
|
})
|
|
41
40
|
|
|
42
|
-
# 🚀 Fluent endpoint definition with automatic validation
|
|
43
41
|
endpoint(
|
|
44
42
|
GET('/books')
|
|
45
|
-
.query(:limit, T.optional(T.integer(
|
|
43
|
+
.query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)))
|
|
46
44
|
.query(:genre, T.optional(T.string))
|
|
47
45
|
.summary('List books with filtering')
|
|
48
46
|
.ok(T.array(BOOK_SCHEMA))
|
|
49
47
|
.build
|
|
50
48
|
) do |inputs|
|
|
51
|
-
# inputs are already validated and type-coerced!
|
|
52
49
|
Book.where(genre: inputs[:genre])
|
|
53
50
|
.limit(inputs[:limit] || 20)
|
|
54
51
|
.map(&:to_h)
|
|
55
52
|
end
|
|
56
|
-
|
|
57
|
-
run! if __FILE__ == $0
|
|
58
53
|
end
|
|
59
54
|
```
|
|
60
55
|
|
|
@@ -76,17 +71,12 @@ end
|
|
|
76
71
|
```ruby
|
|
77
72
|
# Define once, use everywhere
|
|
78
73
|
USER_SCHEMA = T.hash({
|
|
79
|
-
"email" => T.email, #
|
|
80
|
-
"age" => T.optional(T.integer(
|
|
81
|
-
"preferences" => T.hash({
|
|
82
|
-
"newsletter" => T.boolean,
|
|
83
|
-
"theme" => T.enum(['light', 'dark'])
|
|
84
|
-
})
|
|
74
|
+
"email" => T.email, # built-in email validation
|
|
75
|
+
"age" => T.optional(T.integer(minimum: 0, maximum: 150))
|
|
85
76
|
})
|
|
86
77
|
|
|
87
78
|
# Automatic validation + coercion
|
|
88
79
|
endpoint(POST('/users').json_body(USER_SCHEMA).build) do |inputs|
|
|
89
|
-
# inputs[:body] is guaranteed to match USER_SCHEMA
|
|
90
80
|
User.create(inputs[:body])
|
|
91
81
|
end
|
|
92
82
|
```
|
|
@@ -110,37 +100,32 @@ api_resource '/books', schema: BOOK_SCHEMA do
|
|
|
110
100
|
end
|
|
111
101
|
```
|
|
112
102
|
|
|
113
|
-
##
|
|
103
|
+
## From OpenAPI to Running App (Scaffold)
|
|
114
104
|
|
|
115
|
-
|
|
116
|
-
```ruby
|
|
117
|
-
class SecureAPI < SinatraRapiTapir
|
|
118
|
-
rapitapir do
|
|
119
|
-
bearer_auth :api_key
|
|
120
|
-
production_defaults! # Security headers, rate limiting, etc.
|
|
121
|
-
end
|
|
105
|
+
Input: an OpenAPI/Swagger JSON.
|
|
122
106
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
) do
|
|
129
|
-
require_scope!('admin')
|
|
130
|
-
User.all
|
|
131
|
-
end
|
|
132
|
-
end
|
|
133
|
-
```
|
|
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
|
|
134
112
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
|
142
121
|
```
|
|
143
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
|
+
|
|
144
129
|
## Real-World Benefits
|
|
145
130
|
|
|
146
131
|
**🚀 Development Speed**: Define endpoints declaratively, get validation + docs for free
|
|
@@ -159,16 +144,10 @@ Works with your existing Ruby stack:
|
|
|
159
144
|
|
|
160
145
|
```ruby
|
|
161
146
|
# Sinatra (recommended) - clean inheritance
|
|
162
|
-
class API < SinatraRapiTapir; end
|
|
147
|
+
class API < RapiTapir::SinatraRapiTapir; end
|
|
163
148
|
|
|
164
|
-
# Sinatra extension
|
|
149
|
+
# Sinatra extension
|
|
165
150
|
register RapiTapir::Sinatra::Extension
|
|
166
|
-
|
|
167
|
-
# Plain Rack
|
|
168
|
-
use RapiTapir::Server::RackAdapter
|
|
169
|
-
|
|
170
|
-
# Rails controllers (coming soon)
|
|
171
|
-
include RapiTapir::Rails::Controller
|
|
172
151
|
```
|
|
173
152
|
|
|
174
153
|
## The Ruby Community Connection
|
|
@@ -193,24 +172,26 @@ Or add to your Gemfile:
|
|
|
193
172
|
gem 'rapitapir'
|
|
194
173
|
```
|
|
195
174
|
|
|
196
|
-
Check out the
|
|
175
|
+
Check out the examples and docs:
|
|
176
|
+
- Examples: https://github.com/riccardomerolla/rapitapir/tree/main/examples
|
|
177
|
+
- Docs: https://riccardomerolla.github.io/rapitapir
|
|
197
178
|
|
|
198
|
-
## What
|
|
179
|
+
## What’s Next?
|
|
199
180
|
|
|
200
|
-
-
|
|
201
|
-
-
|
|
202
|
-
-
|
|
203
|
-
-
|
|
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
|
|
204
185
|
|
|
205
186
|
## Try It Today
|
|
206
187
|
|
|
207
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.
|
|
208
189
|
|
|
209
190
|
**Links:**
|
|
210
|
-
-
|
|
211
|
-
-
|
|
212
|
-
-
|
|
213
|
-
-
|
|
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
|
|
214
195
|
|
|
215
196
|
---
|
|
216
197
|
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# ADR-0001: Base class strategy (SinatraRapiTapir) vs manual extension
|
|
2
|
+
|
|
3
|
+
Date: 2025-08-08
|
|
4
|
+
Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
Historically, users registered the Sinatra extension manually and wired routes/DSL themselves. This added boilerplate and repeated setup across services, making the first-run experience slower and error-prone.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Adopt a first-class base class, `SinatraRapiTapir`, as the primary way to build APIs:
|
|
13
|
+
|
|
14
|
+
- Auto-registers the RapiTapir Sinatra extension.
|
|
15
|
+
- Exposes the enhanced HTTP verb DSL (GET/POST/...).
|
|
16
|
+
- Provides `development_defaults!` and `production_defaults!` helpers for sensible defaults (CORS/docs/health in dev; security headers/rate limit in prod).
|
|
17
|
+
- Keeps manual registration supported for power users and non-Sinatra stacks.
|
|
18
|
+
|
|
19
|
+
## Consequences
|
|
20
|
+
|
|
21
|
+
- Pros: Minimal boilerplate, consistent defaults, faster time-to-first-endpoint, clearer docs.
|
|
22
|
+
- Cons: Slightly more “magic”; divergence from vanilla Sinatra learning resources.
|
|
23
|
+
- Mitigations: Thorough docs, explicit opt-outs, manual extension path remains supported.
|
|
24
|
+
|
|
25
|
+
## Alternatives considered
|
|
26
|
+
|
|
27
|
+
- Only manual extension: simpler mental model but worse DX and more boilerplate.
|
|
28
|
+
- Separate installer generator: adds tooling complexity without runtime benefit.
|
|
29
|
+
|
|
30
|
+
## Follow-ups
|
|
31
|
+
|
|
32
|
+
- Ensure README and examples prefer `SinatraRapiTapir` while linking manual alternative.
|
|
33
|
+
- Add integration tests for both base class and manual setup to avoid regressions.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# ADR-0002: Type shortcut (T) and type system boundaries
|
|
2
|
+
|
|
3
|
+
Date: 2025-08-08
|
|
4
|
+
Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
The library offers a rich runtime type system (primitives, composites, optionals, constraints, coercion). Frequent usage leads to verbosity (e.g., `RapiTapir::Types.string`).
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
- Provide a global, ergonomic alias `T` to the type system (e.g., `T.string`, `T.array(T.integer)`, `T.hash({ "id" => T.integer })`).
|
|
13
|
+
- Keep the type system strictly runtime-validating with coercion where safe; no mandatory compile-time type checker dependency.
|
|
14
|
+
- Maintain boundaries: core remains independent of Sorbet/RBS; optional generators/adapters may be provided later.
|
|
15
|
+
|
|
16
|
+
## Consequences
|
|
17
|
+
|
|
18
|
+
- Pros: Concise schemas, consistent across DSL and apps, lower ceremony.
|
|
19
|
+
- Cons: Potential namespace collision in extreme cases.
|
|
20
|
+
- Mitigations: `T` is introduced in RapiTapir surface with clear docs; fallback to fully-qualified `RapiTapir::Types` always available.
|
|
21
|
+
|
|
22
|
+
## Alternatives considered
|
|
23
|
+
|
|
24
|
+
- No shortcut: more explicit but verbose.
|
|
25
|
+
- Multiple shortcuts per namespace: increases confusion and conflicts.
|
|
26
|
+
|
|
27
|
+
## Follow-ups
|
|
28
|
+
|
|
29
|
+
- Keep schema examples in docs using `T` for clarity.
|
|
30
|
+
- Provide guidance on custom types and how to avoid collisions.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# ADR-0003: OpenAPI source-of-truth and documentation flow
|
|
2
|
+
|
|
3
|
+
Date: 2025-08-08
|
|
4
|
+
Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
We generate OpenAPI from endpoint definitions. Competing approaches: maintain OpenAPI by hand and generate code from it, or treat the DSL as the single source of truth (SSOT).
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Use the RapiTapir DSL as the SSOT. All documentation artifacts are derived from code:
|
|
13
|
+
|
|
14
|
+
- Generate OpenAPI 3.0.3 (JSON/YAML) from endpoints.
|
|
15
|
+
- Generate interactive HTML docs and Markdown from the same model.
|
|
16
|
+
- Serve docs via CLI/dev server or mount in-app.
|
|
17
|
+
- Avoid editing generated OpenAPI by hand; support customization via DSL metadata and documented extension points.
|
|
18
|
+
|
|
19
|
+
## Consequences
|
|
20
|
+
|
|
21
|
+
- Pros: Docs stay in sync with code; fewer drift bugs; simpler workflow for Ruby teams.
|
|
22
|
+
- Cons: Some OpenAPI-first workflows may need additional annotations in code.
|
|
23
|
+
- Mitigations: Rich metadata helpers (summary/description/tags/examples), selective overrides where needed.
|
|
24
|
+
|
|
25
|
+
## Alternatives considered
|
|
26
|
+
|
|
27
|
+
- OpenAPI-first: stronger language-agnostic posture, but duplicates schema logic and increases drift.
|
|
28
|
+
|
|
29
|
+
## Follow-ups
|
|
30
|
+
|
|
31
|
+
- Add CI job to generate/validate OpenAPI for examples to prevent drift.
|
|
32
|
+
- Document how to inject vendor extensions and examples through DSL metadata.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# ADR-0004: Client generation target (TypeScript first) and interface conventions
|
|
2
|
+
|
|
3
|
+
Date: 2025-08-08
|
|
4
|
+
Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
We can generate clients in multiple languages. The highest demand from users is a typed browser/Node ecosystem client with first-class DX.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Prioritize TypeScript as the official first-class generated client:
|
|
13
|
+
|
|
14
|
+
- Emit strongly-typed request/response models and method signatures.
|
|
15
|
+
- Promise-based API with configurable baseUrl and fetch/adapter options.
|
|
16
|
+
- Typed error envelope for non-2xx responses (e.g., discriminated union or exception type).
|
|
17
|
+
- Keep the generator pluggable to allow future languages (Ruby, Python) without coupling core.
|
|
18
|
+
|
|
19
|
+
## Consequences
|
|
20
|
+
|
|
21
|
+
- Pros: Maximizes reach for frontend/backend TS users; fast feedback loop; strong typing.
|
|
22
|
+
- Cons: Non-TS ecosystems need to wait for parity.
|
|
23
|
+
- Mitigations: Stable generator interface; community templates for other languages.
|
|
24
|
+
|
|
25
|
+
## Conventions
|
|
26
|
+
|
|
27
|
+
- Method names derived from path + HTTP verb; idempotent naming for GET/list/show.
|
|
28
|
+
- Query/path/body segmentation mirrors server types.
|
|
29
|
+
- Semantic versioning of client generator to avoid breaking downstream apps.
|
|
30
|
+
|
|
31
|
+
## Follow-ups
|
|
32
|
+
|
|
33
|
+
- Add examples for browser and Node usage, including auth headers and retries.
|
|
34
|
+
- Track demand for additional languages and prioritize accordingly.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# ADR-0005: Authentication architecture (schemes + helpers + middleware)
|
|
2
|
+
|
|
3
|
+
Date: 2025-08-08
|
|
4
|
+
Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
APIs require flexible authentication/authorization mechanisms. We support OAuth2/JWT, bearer/api-key/basic, and scope-based access control across different stacks.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Adopt a layered auth architecture:
|
|
13
|
+
|
|
14
|
+
- Schemes: `RapiTapir::Auth::Schemes::*` (Bearer, JWT, OAuth2, Basic, ApiKey) encapsulate parsing/verification and `challenge` strings.
|
|
15
|
+
- Middleware: Authentication (build context), Authorization (scope checks), SecurityHeaders, CORS, RateLimiting.
|
|
16
|
+
- Helpers: In Sinatra integration, expose `authenticate_oauth2`, `authorize_oauth2!`, `authenticated?`, `has_scope?`, and `current_auth_context`.
|
|
17
|
+
- Provider-agnostic: Auth0 and generic OAuth2 supported via configuration; JWKS-based JWT verification.
|
|
18
|
+
|
|
19
|
+
## Consequences
|
|
20
|
+
|
|
21
|
+
- Pros: Clear separation, testable units, provider flexibility, easy to reason about.
|
|
22
|
+
- Cons: Multiple layers increase surface area.
|
|
23
|
+
- Mitigations: Defaults for common cases; comprehensive examples and specs.
|
|
24
|
+
|
|
25
|
+
## Alternatives considered
|
|
26
|
+
|
|
27
|
+
- Hard-wire to a specific provider: faster initially but vendor lock-in and reduced portability.
|
|
28
|
+
|
|
29
|
+
## Follow-ups
|
|
30
|
+
|
|
31
|
+
- Convert pending OAuth2/JWT tests to pass using deterministic JWKS fixtures.
|
|
32
|
+
- Document error semantics and standardize WWW-Authenticate challenges across schemes.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# ADR-0006: Observability defaults (health, logging, metrics/tracing hooks)
|
|
2
|
+
|
|
3
|
+
Date: 2025-08-08
|
|
4
|
+
Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
Production services benefit from consistent, low-friction observability. The library ships helpers and middleware for health, logging, metrics, and tracing, while keeping exporters optional.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
- Development defaults enable: health endpoint, CORS, docs, basic metrics/logging.
|
|
13
|
+
- Production defaults focus on security headers and safe defaults; observability can be enabled via explicit configuration blocks.
|
|
14
|
+
- Provide hooks for Prometheus metrics and OpenTelemetry tracing; do not hard-depend on vendors.
|
|
15
|
+
- Health check registry supports built-in and custom checks.
|
|
16
|
+
|
|
17
|
+
## Consequences
|
|
18
|
+
|
|
19
|
+
- Pros: Fast local experience, predictable prod posture, portable observability across vendors.
|
|
20
|
+
- Cons: Users may expect batteries-included exporters.
|
|
21
|
+
- Mitigations: Snippets and guides for wiring popular backends; small glue modules where useful.
|
|
22
|
+
|
|
23
|
+
## Alternatives considered
|
|
24
|
+
|
|
25
|
+
- Ship tight integrations by default: increases maintenance and pulls heavy deps into core.
|
|
26
|
+
|
|
27
|
+
## Follow-ups
|
|
28
|
+
|
|
29
|
+
- Add labeled metrics examples and OTLP wiring snippets.
|
|
30
|
+
- Provide a minimal benchmark/perf budget harness to monitor overhead.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# ADR-0007: AI features scope (RAG/LLM/MCP) and maintainability boundaries
|
|
2
|
+
|
|
3
|
+
Date: 2025-08-08
|
|
4
|
+
Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
RapiTapir includes AI-adjacent features: LLM instruction generation, a simple RAG pipeline (memory backend), and MCP export for agent tooling. These should remain optional and decoupled from core HTTP concerns.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
- Namespace AI features under `RapiTapir::AI` and keep them opt-in.
|
|
13
|
+
- Provide provider-agnostic interfaces; avoid hard vendor locks and network calls in core.
|
|
14
|
+
- Ship deterministic test doubles and local-only defaults (e.g., memory backend) for reliability.
|
|
15
|
+
- Limit feature scope to developer tooling and augmentation (instructions, docs, context), not business logic.
|
|
16
|
+
|
|
17
|
+
## Consequences
|
|
18
|
+
|
|
19
|
+
- Pros: Clear boundaries, low risk to core stability, easy to disable.
|
|
20
|
+
- Cons: Smaller immediate feature set vs vendor SDKs.
|
|
21
|
+
- Mitigations: Extension points for providers; examples that demonstrate integration without coupling.
|
|
22
|
+
|
|
23
|
+
## Alternatives considered
|
|
24
|
+
|
|
25
|
+
- Deep vendor integrations in core: faster to demo, harder to maintain and test.
|
|
26
|
+
|
|
27
|
+
## Follow-ups
|
|
28
|
+
|
|
29
|
+
- Add guidance on switching RAG backends and plugging external vector stores.
|
|
30
|
+
- Provide examples for MCP export consumption in popular agents.
|
data/docs/adr/README.md
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Architectural Decision Records (ADRs)
|
|
2
|
+
|
|
3
|
+
This directory contains Architecture Decision Records (ADRs) that document significant architectural decisions made throughout the RapiTapir project.
|
|
4
|
+
|
|
5
|
+
## Purpose
|
|
6
|
+
|
|
7
|
+
- Maintain a clear history of architectural choices and their rationale.
|
|
8
|
+
- Provide context and rationale for future maintainers and contributors.
|
|
9
|
+
|
|
10
|
+
## ADR Structure
|
|
11
|
+
|
|
12
|
+
Each ADR is a Markdown file with a sequential identifier and a descriptive title:
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
NNNN-short-title.md
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Inside, ADRs follow this structure:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
# ADR NNNN: Short Title
|
|
22
|
+
|
|
23
|
+
Date: YYYY-MM-DD
|
|
24
|
+
|
|
25
|
+
## Status
|
|
26
|
+
|
|
27
|
+
Proposed | Accepted | Deprecated
|
|
28
|
+
|
|
29
|
+
## Context
|
|
30
|
+
|
|
31
|
+
Describe the context and forces leading to this decision.
|
|
32
|
+
|
|
33
|
+
## Decision
|
|
34
|
+
|
|
35
|
+
Describe the decision and its rationale.
|
|
36
|
+
|
|
37
|
+
## Consequences
|
|
38
|
+
|
|
39
|
+
Describe the resulting consequences, trade-offs, and impacts.
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Creating a New ADR
|
|
43
|
+
|
|
44
|
+
1. Copy `template.md` and rename to the next sequence number, e.g., `0002-add-auth-cache.md`.
|
|
45
|
+
2. Fill in date, status, context, decision, and consequences.
|
|
46
|
+
3. Commit the new ADR file to the repository.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# ADR-NNNN: Title
|
|
2
|
+
|
|
3
|
+
Date: YYYY-MM-DD
|
|
4
|
+
Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
Describe the background and forces leading to this decision.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Record the decision made, with enough detail to be unambiguous.
|
|
13
|
+
|
|
14
|
+
## Consequences
|
|
15
|
+
|
|
16
|
+
List positive, negative, and neutral consequences. Consider security, performance, DX, and maintenance.
|
|
17
|
+
|
|
18
|
+
## Alternatives considered
|
|
19
|
+
|
|
20
|
+
Briefly list alternatives and why they were not chosen.
|
|
21
|
+
|
|
22
|
+
## Follow-ups
|
|
23
|
+
|
|
24
|
+
List tasks, docs, or changes required to uphold this decision.
|