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
data/docs/blueprint.md
CHANGED
|
@@ -1,6 +1,94 @@
|
|
|
1
|
-
# Ruby Tapir
|
|
2
|
-
|
|
3
|
-
A Ruby library for describing, serving, consuming, and documenting HTTP APIs with type safety and developer experience
|
|
1
|
+
# RapiTapir (formerly "Ruby Tapir") – Type-Safe HTTP API Library
|
|
2
|
+
|
|
3
|
+
A Ruby library for describing, serving, consuming, and documenting HTTP APIs with type safety and great developer experience.
|
|
4
|
+
|
|
5
|
+
## Status update — August 2025
|
|
6
|
+
|
|
7
|
+
This document started as an early blueprint. The project has since shipped a substantial v2.0 with many areas exceeding the original scope. Below is a concise snapshot of where we are and what we should tackle next.
|
|
8
|
+
|
|
9
|
+
### What’s implemented and usable today
|
|
10
|
+
|
|
11
|
+
- Core DSL and Types
|
|
12
|
+
- Fluent HTTP verb DSL (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH)
|
|
13
|
+
- Global T shortcut (e.g., T.string) and rich type system with validation/coercion
|
|
14
|
+
- Resource builder (CRUD), error responses, metadata (summary, description, tags)
|
|
15
|
+
- Servers and runtime
|
|
16
|
+
- Rack adapter and Sinatra base class (SinatraRapiTapir) with zero-boilerplate startup
|
|
17
|
+
- Middleware: CORS, Security headers, Rate limiting, Request logging, Exception handler
|
|
18
|
+
- Health checks and observability hooks (metrics, logging, tracing scaffolding)
|
|
19
|
+
- Tooling and docs
|
|
20
|
+
- OpenAPI 3.0.3 generator (JSON/YAML) + interactive HTML docs + Markdown docs
|
|
21
|
+
- TypeScript client generator with types and request/response modeling
|
|
22
|
+
- CLI: generate openapi/docs/client, validate, serve
|
|
23
|
+
- Authentication
|
|
24
|
+
- OAuth2/JWT schemes, bearer/api-key/basic auth, scope-based authorization helpers
|
|
25
|
+
- AI features (distinctive)
|
|
26
|
+
- RAG pipeline (memory backend), LLM instruction generator, MCP exporter
|
|
27
|
+
- Serverless examples (new)
|
|
28
|
+
- Examples for AWS Lambda, Google Cloud Functions, Azure Functions, and Vercel
|
|
29
|
+
|
|
30
|
+
### Quality gates snapshot
|
|
31
|
+
|
|
32
|
+
- Tests: 643 passing, 55 pending (primarily OAuth2 integration/helpers due to test infra)
|
|
33
|
+
- Coverage: ~67.6% line coverage, ~39.3% branch coverage
|
|
34
|
+
- Build: rspec green locally; CLI flows validated via specs
|
|
35
|
+
|
|
36
|
+
### Notable gaps and risks
|
|
37
|
+
|
|
38
|
+
1. Multipart/form-data & file uploads
|
|
39
|
+
- Missing first-class multipart parsing, file validations (size, type), and streaming
|
|
40
|
+
2. Streaming/SSE/WebSockets
|
|
41
|
+
- No streaming response primitives, SSE helpers, or WebSocket integration
|
|
42
|
+
3. Rails integration depth
|
|
43
|
+
- Foundational modules and route helpers exist; needs deeper, ergonomic controller wiring
|
|
44
|
+
4. OAuth2 test infrastructure
|
|
45
|
+
- 55 pending specs rely on external JWT/JWKS/WebMock setup; needs deterministic fixtures
|
|
46
|
+
5. Request body naming consistency
|
|
47
|
+
- Handlers typically receive JSON under `:body`; align docs/tests (deprecate `:data` alias)
|
|
48
|
+
6. Documentation drift
|
|
49
|
+
- Some README snippets are truncated or schematic; ensure copy-paste runnable examples
|
|
50
|
+
7. Performance and budgets
|
|
51
|
+
- No standardized benchmark suite or perf budgets in CI; schema caching hot paths can improve
|
|
52
|
+
8. API stability and versioning
|
|
53
|
+
- Clarify SemVer guarantees, deprecations policy, and extension points
|
|
54
|
+
9. Error model consistency
|
|
55
|
+
- Consider standard Problem Details (RFC 7807) responses and uniform error envelopes
|
|
56
|
+
|
|
57
|
+
### Prioritized improvements (next 4–8 weeks)
|
|
58
|
+
|
|
59
|
+
- P0 – Test & DX hardening (1–2 weeks)
|
|
60
|
+
- Convert OAuth2/JWT specs from pending to passing using local JWKS fixtures/mocks
|
|
61
|
+
- Normalize request body to `inputs[:body]` in docs/tests; add deprecation notice for `:data`
|
|
62
|
+
- Fix/validate README code blocks; add a doc-examples smoke test in CI
|
|
63
|
+
- Raise coverage to ≥75% by adding failure-path tests for DSL, middleware, and generators
|
|
64
|
+
|
|
65
|
+
- P1 – Multipart/form-data + content negotiation (2–3 weeks)
|
|
66
|
+
- Add `multipart_body`, `file_part`, `form_field`, content-type validation, and max-size limits
|
|
67
|
+
- Stream uploads to tempfiles; pluggable validators for MIME/type magic
|
|
68
|
+
|
|
69
|
+
- P2 – Rails deep integration (2–3 weeks)
|
|
70
|
+
- Controller macro to mount endpoints with automatic validation/serialization
|
|
71
|
+
- Error mapping to Rails responders; parameter extraction; generators/scaffolds
|
|
72
|
+
|
|
73
|
+
- P3 – Streaming primitives (3–4 weeks)
|
|
74
|
+
- SSE helper (`.out(stream_body(...))`), chunked responses; foundational WebSocket adapter design
|
|
75
|
+
|
|
76
|
+
- P3 – Performance/observability (parallel, 1–2 weeks)
|
|
77
|
+
- Add microbench suite (endpoint build, request path, serialization); cache compiled schemas
|
|
78
|
+
- Optional OTLP tracing exporter wiring helper and labeled Prometheus metrics out-of-the-box
|
|
79
|
+
|
|
80
|
+
### ADRs and decision tracking
|
|
81
|
+
|
|
82
|
+
- A new `docs/adr/` directory is in place. Suggested initial ADRs:
|
|
83
|
+
- [ADR-0001: Base class strategy (SinatraRapiTapir) vs manual extension](adr/0001-base-class-strategy.md)
|
|
84
|
+
- [ADR-0002: Type shortcut (T) and type system boundaries](adr/0002-type-shortcut-and-type-system.md)
|
|
85
|
+
- [ADR-0003: OpenAPI source-of-truth and doc generation flow](adr/0003-openapi-source-of-truth.md)
|
|
86
|
+
- [ADR-0004: Client generation target (TypeScript first) and interface conventions](adr/0004-client-generation-typescript-first.md)
|
|
87
|
+
- [ADR-0005: Authentication architecture (schemes + helpers + middleware)](adr/0005-auth-architecture.md)
|
|
88
|
+
- [ADR-0006: Observability defaults (health, logging, metrics/tracing hooks)](adr/0006-observability-defaults.md)
|
|
89
|
+
- [ADR-0007: AI features scope (RAG/LLM/MCP) and maintainability boundaries](adr/0007-ai-scope-and-boundaries.md)
|
|
90
|
+
|
|
91
|
+
The remainder of this document preserves the original blueprint for historical context and broader roadmap.
|
|
4
92
|
|
|
5
93
|
## Repository Structure
|
|
6
94
|
|
|
@@ -414,7 +502,7 @@ Tapir::Docs::SwaggerUI.mount(openapi_spec, path: "/docs")
|
|
|
414
502
|
### Technical Metrics
|
|
415
503
|
- **Performance**: < 1ms overhead for simple endpoints
|
|
416
504
|
- **Memory**: < 10MB memory overhead for typical applications
|
|
417
|
-
- **Compatibility**: Support for Ruby 3.
|
|
505
|
+
- **Compatibility**: Support for Ruby 3.3+ and all major frameworks
|
|
418
506
|
- **Coverage**: > 95% test coverage across all components
|
|
419
507
|
|
|
420
508
|
### Developer Experience Metrics
|