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.
Files changed (161) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +7 -7
  3. data/.rubocop_todo.yml +88 -0
  4. data/CHANGELOG.md +29 -1
  5. data/README.md +1339 -236
  6. data/RUBY_WEEKLY_LAUNCH_POST.md +200 -0
  7. data/docs/RAILS_INTEGRATION_IMPLEMENTATION.md +209 -0
  8. data/docs/SINATRA_EXTENSION.md +399 -348
  9. data/docs/STRICT_VALIDATION.md +229 -0
  10. data/docs/VALIDATION_IMPROVEMENTS.md +218 -0
  11. data/docs/adr/0001-base-class-strategy.md +33 -0
  12. data/docs/adr/0002-type-shortcut-and-type-system.md +30 -0
  13. data/docs/adr/0003-openapi-source-of-truth.md +32 -0
  14. data/docs/adr/0004-client-generation-typescript-first.md +34 -0
  15. data/docs/adr/0005-auth-architecture.md +32 -0
  16. data/docs/adr/0006-observability-defaults.md +30 -0
  17. data/docs/adr/0007-ai-scope-and-boundaries.md +30 -0
  18. data/docs/adr/README.md +46 -0
  19. data/docs/adr/template.md +24 -0
  20. data/docs/ai-integration-plan.md +112 -0
  21. data/docs/auto-derivation.md +505 -92
  22. data/docs/blueprint.md +92 -4
  23. data/docs/endpoint-definition.md +536 -129
  24. data/docs/implementation-status.md +1 -1
  25. data/docs/n8n-integration.md +212 -0
  26. data/docs/observability.md +810 -500
  27. data/docs/using-mcp.md +93 -0
  28. data/examples/ai/knowledge_base_rag.rb +83 -0
  29. data/examples/ai/user_management_mcp.rb +92 -0
  30. data/examples/ai/user_validation_llm.rb +187 -0
  31. data/examples/auto_derivation_ruby_friendly.rb +44 -113
  32. data/examples/cli/user_api_endpoints.rb +63 -36
  33. data/examples/demo_api.rb +57 -18
  34. data/examples/enterprise_extension_demo.rb +13 -13
  35. data/examples/enterprise_rapitapir_api.rb +81 -93
  36. data/examples/nocodb/nocodb_scaffold/Gemfile +22 -0
  37. data/examples/nocodb/nocodb_scaffold/README.md +10 -0
  38. data/examples/nocodb/nocodb_scaffold/Rakefile +7 -0
  39. data/examples/nocodb/nocodb_scaffold/app/api/app.rb +1139 -0
  40. data/examples/nocodb/nocodb_scaffold/app/models/email_template.rb +6 -0
  41. data/examples/nocodb/nocodb_scaffold/app/models/faq.rb +6 -0
  42. data/examples/nocodb/nocodb_scaffold/app/models/feature.rb +6 -0
  43. data/examples/nocodb/nocodb_scaffold/app/models/idea.rb +6 -0
  44. data/examples/nocodb/nocodb_scaffold/app/models/itinerary_day.rb +6 -0
  45. data/examples/nocodb/nocodb_scaffold/app/models/route.rb +6 -0
  46. data/examples/nocodb/nocodb_scaffold/app/models/subscriber.rb +6 -0
  47. data/examples/nocodb/nocodb_scaffold/app/models/tour.rb +6 -0
  48. data/examples/nocodb/nocodb_scaffold/app/models/webhook.rb +6 -0
  49. data/examples/nocodb/nocodb_scaffold/app/models_loader.rb +3 -0
  50. data/examples/nocodb/nocodb_scaffold/config/database.yml +11 -0
  51. data/examples/nocodb/nocodb_scaffold/config.ru +9 -0
  52. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152012_create_features.rb +10 -0
  53. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152013_create_tours.rb +10 -0
  54. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152014_create_routes.rb +10 -0
  55. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152015_create_itinerary_days.rb +10 -0
  56. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152016_create_subscribers.rb +10 -0
  57. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152017_create_email_templates.rb +10 -0
  58. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152018_create_faqs.rb +10 -0
  59. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152019_create_webhooks.rb +10 -0
  60. data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152020_create_ideas.rb +10 -0
  61. data/examples/nocodb/swagger.json +4378 -0
  62. data/examples/production_ready_example.rb +78 -58
  63. data/examples/rails/RAILS_8_GUIDE.md +165 -0
  64. data/examples/rails/RAILS_LOADING_FIX.rb +35 -0
  65. data/examples/rails/README.md +497 -0
  66. data/examples/rails/comprehensive_test.rb +91 -0
  67. data/examples/rails/config/routes.rb +48 -0
  68. data/examples/rails/debug_controller.rb +63 -0
  69. data/examples/rails/detailed_test.rb +46 -0
  70. data/examples/rails/enhanced_users_controller.rb +278 -0
  71. data/examples/rails/final_server_test.rb +50 -0
  72. data/examples/rails/hello_world_app.rb +116 -0
  73. data/examples/rails/hello_world_controller.rb +186 -0
  74. data/examples/rails/hello_world_routes.rb +28 -0
  75. data/examples/rails/rails8_minimal_demo.rb +132 -0
  76. data/examples/rails/rails8_simple_demo.rb +140 -0
  77. data/examples/rails/rails8_working_demo.rb +255 -0
  78. data/examples/rails/real_world_blog_api.rb +510 -0
  79. data/examples/rails/server_test.rb +46 -0
  80. data/examples/rails/test_direct_processing.rb +41 -0
  81. data/examples/rails/test_hello_world.rb +80 -0
  82. data/examples/rails/test_rails_integration.rb +54 -0
  83. data/examples/rails/traditional_app/Gemfile +37 -0
  84. data/examples/rails/traditional_app/README.md +265 -0
  85. data/examples/rails/traditional_app/app/controllers/api/v1/posts_controller.rb +254 -0
  86. data/examples/rails/traditional_app/app/controllers/api/v1/users_controller.rb +220 -0
  87. data/examples/rails/traditional_app/app/controllers/application_controller.rb +86 -0
  88. data/examples/rails/traditional_app/app/controllers/application_controller_simplified.rb +87 -0
  89. data/examples/rails/traditional_app/app/controllers/documentation_controller.rb +149 -0
  90. data/examples/rails/traditional_app/app/controllers/health_controller.rb +42 -0
  91. data/examples/rails/traditional_app/config/routes.rb +25 -0
  92. data/examples/rails/traditional_app/config/routes_best_practice.rb +25 -0
  93. data/examples/rails/traditional_app/config/routes_simplified.rb +36 -0
  94. data/examples/rails/traditional_app_runnable.rb +406 -0
  95. data/examples/rails/users_controller.rb +4 -1
  96. data/examples/serverless/Gemfile +43 -0
  97. data/examples/serverless/QUICKSTART.md +331 -0
  98. data/examples/serverless/README.md +520 -0
  99. data/examples/serverless/aws_lambda_example.rb +307 -0
  100. data/examples/serverless/aws_sam_template.yaml +215 -0
  101. data/examples/serverless/azure_functions_example.rb +407 -0
  102. data/examples/serverless/deploy.rb +204 -0
  103. data/examples/serverless/gcp_cloud_functions_example.rb +367 -0
  104. data/examples/serverless/gcp_function.yaml +23 -0
  105. data/examples/serverless/host.json +24 -0
  106. data/examples/serverless/package.json +32 -0
  107. data/examples/serverless/spec/aws_lambda_spec.rb +196 -0
  108. data/examples/serverless/spec/spec_helper.rb +89 -0
  109. data/examples/serverless/vercel.json +31 -0
  110. data/examples/serverless/vercel_example.rb +404 -0
  111. data/examples/simple_demo_api.rb +40 -7
  112. data/examples/strict_validation_examples.rb +104 -0
  113. data/examples/user_api.rb +130 -132
  114. data/examples/validation_error_examples.rb +173 -0
  115. data/lib/rapitapir/ai/llm_instruction.rb +456 -0
  116. data/lib/rapitapir/ai/mcp.rb +134 -0
  117. data/lib/rapitapir/ai/rag.rb +287 -0
  118. data/lib/rapitapir/ai/rag_middleware.rb +147 -0
  119. data/lib/rapitapir/auth/oauth2.rb +44 -58
  120. data/lib/rapitapir/cli/command.rb +392 -6
  121. data/lib/rapitapir/cli/mcp_export.rb +18 -0
  122. data/lib/rapitapir/cli/scaffold_generator.rb +639 -0
  123. data/lib/rapitapir/cli/validator.rb +3 -7
  124. data/lib/rapitapir/core/endpoint.rb +59 -6
  125. data/lib/rapitapir/core/enhanced_endpoint.rb +3 -7
  126. data/lib/rapitapir/dsl/enhanced_structures.rb +1 -1
  127. data/lib/rapitapir/dsl/fluent_endpoint_builder.rb +53 -0
  128. data/lib/rapitapir/endpoint_registry.rb +47 -0
  129. data/lib/rapitapir/observability/health_check.rb +4 -4
  130. data/lib/rapitapir/observability/logging.rb +10 -10
  131. data/lib/rapitapir/openapi/schema_generator.rb +46 -2
  132. data/lib/rapitapir/schema.rb +2 -2
  133. data/lib/rapitapir/server/enhanced_rack_adapter.rb +11 -8
  134. data/lib/rapitapir/server/middleware.rb +2 -2
  135. data/lib/rapitapir/server/rack_adapter.rb +1 -3
  136. data/lib/rapitapir/server/rails/configuration.rb +77 -0
  137. data/lib/rapitapir/server/rails/controller_base.rb +185 -0
  138. data/lib/rapitapir/server/rails/documentation_helpers.rb +76 -0
  139. data/lib/rapitapir/server/rails/resource_builder.rb +181 -0
  140. data/lib/rapitapir/server/rails/routes.rb +114 -0
  141. data/lib/rapitapir/server/rails_adapter.rb +10 -3
  142. data/lib/rapitapir/server/rails_adapter_class.rb +1 -3
  143. data/lib/rapitapir/server/rails_controller.rb +1 -3
  144. data/lib/rapitapir/server/rails_integration.rb +67 -0
  145. data/lib/rapitapir/server/rails_response_handler.rb +16 -3
  146. data/lib/rapitapir/server/sinatra_adapter.rb +29 -5
  147. data/lib/rapitapir/server/sinatra_integration.rb +4 -4
  148. data/lib/rapitapir/sinatra/extension.rb +2 -2
  149. data/lib/rapitapir/sinatra/oauth2_helpers.rb +34 -40
  150. data/lib/rapitapir/types/array.rb +4 -0
  151. data/lib/rapitapir/types/auto_derivation.rb +4 -20
  152. data/lib/rapitapir/types/datetime.rb +1 -3
  153. data/lib/rapitapir/types/float.rb +2 -6
  154. data/lib/rapitapir/types/hash.rb +40 -2
  155. data/lib/rapitapir/types/integer.rb +4 -12
  156. data/lib/rapitapir/types/object.rb +6 -2
  157. data/lib/rapitapir/types.rb +6 -2
  158. data/lib/rapitapir/version.rb +1 -1
  159. data/lib/rapitapir.rb +5 -3
  160. data/rapitapir.gemspec +3 -2
  161. metadata +142 -8
@@ -0,0 +1,185 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative '../rails_controller'
4
+ require_relative '../../dsl/http_verbs'
5
+ require_relative '../../types'
6
+ require_relative 'resource_builder'
7
+ require_relative 'configuration'
8
+
9
+ module RapiTapir
10
+ module Server
11
+ module Rails
12
+ # Enhanced Rails controller base class providing Sinatra-like experience
13
+ #
14
+ # This class bridges the gap between Sinatra's elegant DSL and Rails conventions,
15
+ # offering the same clean syntax that Sinatra developers enjoy.
16
+ #
17
+ # @example Basic usage
18
+ # class UsersController < RapiTapir::Server::Rails::ControllerBase
19
+ # rapitapir do
20
+ # info(title: 'Users API', version: '1.0.0')
21
+ # development_defaults!
22
+ # end
23
+ #
24
+ # USER_SCHEMA = T.hash({
25
+ # "id" => T.integer,
26
+ # "name" => T.string,
27
+ # "email" => T.email
28
+ # })
29
+ #
30
+ # endpoint(
31
+ # GET('/users')
32
+ # .summary('List users')
33
+ # .ok(T.array(USER_SCHEMA))
34
+ # .build
35
+ # ) { User.all.map(&:attributes) }
36
+ # end
37
+ class ControllerBase < ActionController::Base
38
+ include RapiTapir::Server::Rails::Controller
39
+ extend RapiTapir::DSL::HTTPVerbs
40
+
41
+ # Make T shortcut available in Rails controllers
42
+ T = RapiTapir::Types
43
+
44
+ class << self
45
+ # Configure RapiTapir for this controller
46
+ # Similar to Sinatra's rapitapir block
47
+ #
48
+ # @param block [Proc] Configuration block
49
+ # @example
50
+ # rapitapir do
51
+ # info(title: 'My API', version: '1.0.0')
52
+ # development_defaults!
53
+ # end
54
+ def rapitapir(&)
55
+ @rapitapir_config = Configuration.new
56
+ @rapitapir_config.instance_eval(&) if block_given?
57
+ setup_default_features
58
+ end
59
+
60
+ # Define an endpoint with automatic action generation
61
+ # This method creates both the endpoint definition and the corresponding Rails action
62
+ #
63
+ # @param endpoint_definition [RapiTapir::Core::Endpoint] The endpoint definition
64
+ # @param block [Proc] The endpoint handler
65
+ # @example
66
+ # endpoint(
67
+ # GET('/users/:id')
68
+ # .summary('Get user')
69
+ # .path_param(:id, T.integer)
70
+ # .ok(USER_SCHEMA)
71
+ # .build
72
+ # ) do |inputs|
73
+ # User.find(inputs[:id]).attributes
74
+ # end
75
+ def endpoint(endpoint_definition, &)
76
+ action_name = derive_action_name(endpoint_definition.path, endpoint_definition.method)
77
+
78
+ # Register endpoint with the Rails controller mixin
79
+ rapitapir_endpoint(action_name, endpoint_definition, &)
80
+
81
+ # Auto-generate Rails controller action that passes the correct action name
82
+ define_method(action_name) do
83
+ process_rapitapir_endpoint(action_name)
84
+ end
85
+ end
86
+
87
+ # Create RESTful resource endpoints with CRUD operations
88
+ # Mirrors Sinatra's api_resource functionality for Rails
89
+ #
90
+ # @param path [String] Base path for the resource
91
+ # @param schema [Object] Schema for the resource
92
+ # @param block [Proc] Resource configuration block
93
+ # @example
94
+ # api_resource '/users', schema: USER_SCHEMA do
95
+ # crud do
96
+ # index { User.all.map(&:attributes) }
97
+ # show { |inputs| User.find(inputs[:id]).attributes }
98
+ # create { |inputs| User.create!(inputs[:body]).attributes }
99
+ # end
100
+ # end
101
+ def api_resource(path, schema:, &block)
102
+ resource_builder = ResourceBuilder.new(self, path, schema)
103
+ resource_builder.instance_eval(&block)
104
+
105
+ # Generate all CRUD endpoints and actions automatically
106
+ resource_builder.endpoints.each do |endpoint_def, handler|
107
+ endpoint(endpoint_def, &handler)
108
+ end
109
+ end
110
+
111
+ # Enhanced HTTP verb methods that return FluentEndpointBuilder
112
+ # These override the mixin methods to ensure proper scoping
113
+ #
114
+ # @param path [String] The endpoint path
115
+ # @return [RapiTapir::DSL::FluentEndpointBuilder] Builder for method chaining
116
+ def GET(path)
117
+ RapiTapir.get(path)
118
+ end
119
+
120
+ def POST(path)
121
+ RapiTapir.post(path)
122
+ end
123
+
124
+ def PUT(path)
125
+ RapiTapir.put(path)
126
+ end
127
+
128
+ def PATCH(path)
129
+ RapiTapir.patch(path)
130
+ end
131
+
132
+ def DELETE(path)
133
+ RapiTapir.delete(path)
134
+ end
135
+
136
+ def HEAD(path)
137
+ RapiTapir.head(path)
138
+ end
139
+
140
+ def OPTIONS(path)
141
+ RapiTapir.options(path)
142
+ end
143
+
144
+ private
145
+
146
+ # Set up default features similar to Sinatra extension
147
+ def setup_default_features
148
+ # Future: Auto-setup CORS, docs, health checks like Sinatra
149
+ # For now, we'll focus on the core functionality
150
+ end
151
+
152
+ # Derive Rails action name from HTTP method and path
153
+ # Follows Rails conventions for RESTful routes
154
+ #
155
+ # @param path [String] The endpoint path
156
+ # @param method [Symbol] The HTTP method
157
+ # @return [Symbol] The Rails action name
158
+ def derive_action_name(path, method)
159
+ # For custom endpoints, always derive from path to avoid conflicts
160
+ path_segments = path.split('/').reject(&:empty?)
161
+
162
+ return method.to_s.downcase.to_sym if path_segments.empty?
163
+
164
+ # Get the main path segment (not parameters)
165
+ main_segment = nil
166
+ path_segments.each do |segment|
167
+ unless segment.start_with?(':') || segment.start_with?('{')
168
+ main_segment = segment
169
+ break
170
+ end
171
+ end
172
+
173
+ if main_segment
174
+ # Create action name from method + segment to ensure uniqueness
175
+ :"#{method.to_s.downcase}_#{main_segment}"
176
+ else
177
+ # Fallback to method name
178
+ method.to_s.downcase.to_sym
179
+ end
180
+ end
181
+ end
182
+ end
183
+ end
184
+ end
185
+ end
@@ -0,0 +1,76 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative '../../openapi/schema_generator'
4
+ require_relative '../../sinatra/swagger_ui_generator'
5
+
6
+ module RapiTapir
7
+ module Server
8
+ module Rails
9
+ # Documentation helpers for Rails controllers
10
+ module DocumentationHelpers
11
+ # Generate OpenAPI specification from Rails controller endpoints
12
+ def generate_openapi_spec_for_controller(controller_class, config = {})
13
+ endpoints = []
14
+
15
+ endpoints = controller_class.rapitapir_endpoints.values.map { |ep_config| ep_config[:endpoint] } if controller_class.respond_to?(:rapitapir_endpoints)
16
+
17
+ info = {
18
+ title: 'API Documentation',
19
+ version: '1.0.0',
20
+ description: 'Generated with RapiTapir for Rails'
21
+ }.merge(config[:info] || {})
22
+
23
+ servers = config[:servers] || [
24
+ {
25
+ url: 'http://localhost:9292',
26
+ description: 'Development server (Rails)'
27
+ }
28
+ ]
29
+
30
+ generator = RapiTapir::OpenAPI::SchemaGenerator.new(
31
+ endpoints: endpoints,
32
+ info: info,
33
+ servers: servers
34
+ )
35
+
36
+ generator.generate
37
+ end
38
+
39
+ # Generate Swagger UI HTML for Rails
40
+ def generate_swagger_ui_html(openapi_path, api_info)
41
+ RapiTapir::Sinatra::SwaggerUIGenerator.new(openapi_path, api_info).generate
42
+ end
43
+
44
+ # Create documentation routes for a Rails controller
45
+ def add_documentation_routes(controller_class, config = {})
46
+ docs_path = config[:docs_path] || '/docs'
47
+ openapi_path = config[:openapi_path] || '/openapi.json'
48
+
49
+ # OpenAPI JSON endpoint
50
+ get openapi_path, to: proc { |_env|
51
+ spec = RapiTapir::Server::Rails::DocumentationHelpers.generate_openapi_spec_for_controller(controller_class, config)
52
+ [
53
+ 200,
54
+ { 'Content-Type' => 'application/json' },
55
+ [JSON.pretty_generate(spec)]
56
+ ]
57
+ }
58
+
59
+ # Swagger UI endpoint
60
+ get docs_path, to: proc { |_env|
61
+ api_info = config[:info] || { title: 'API Documentation' }
62
+ html = RapiTapir::Server::Rails::DocumentationHelpers.generate_swagger_ui_html(openapi_path, api_info)
63
+ [
64
+ 200,
65
+ { 'Content-Type' => 'text/html' },
66
+ [html]
67
+ ]
68
+ }
69
+ end
70
+
71
+ # Module methods for static access
72
+ module_function :generate_openapi_spec_for_controller, :generate_swagger_ui_html
73
+ end
74
+ end
75
+ end
76
+ end
@@ -0,0 +1,181 @@
1
+ # frozen_string_literal: true
2
+
3
+ module RapiTapir
4
+ module Server
5
+ module Rails
6
+ # Resource builder for creating RESTful API endpoints in Rails controllers
7
+ # Provides the same functionality as Sinatra::ResourceBuilder but adapted for Rails
8
+ class ResourceBuilder
9
+ attr_reader :endpoints
10
+
11
+ def initialize(controller_class, base_path, schema, **options)
12
+ @controller_class = controller_class
13
+ @base_path = base_path.chomp('/')
14
+ @schema = schema
15
+ @options = options
16
+ @endpoints = []
17
+ end
18
+
19
+ # Enable standard CRUD operations
20
+ # @param except [Array<Symbol>] Operations to exclude
21
+ # @param only [Array<Symbol>] Only include these operations
22
+ # @param block [Proc] Block defining the CRUD handlers
23
+ def crud(except: [], only: nil, **handlers, &block)
24
+ operations = only || %i[index show create update destroy]
25
+ operations -= except if except.any?
26
+
27
+ # If a block is given, evaluate it in the context of this ResourceBuilder
28
+ if block_given?
29
+ instance_eval(&block)
30
+ else
31
+ # Legacy style with handlers hash
32
+ operations.each do |operation|
33
+ send(operation, &handlers[operation]) if respond_to?(operation, true)
34
+ end
35
+ end
36
+ end
37
+
38
+ # List all resources (GET /resources)
39
+ # @param options [Hash] Endpoint options
40
+ # @param handler [Proc] Request handler
41
+ def index(**options, &handler)
42
+ handler ||= proc { [] }
43
+
44
+ endpoint_def = @controller_class.GET(@base_path)
45
+ .summary(options[:summary] || "List all #{resource_name}")
46
+ .description(options[:description] || "Retrieve a list of #{resource_name}")
47
+ .then { |ep| add_pagination_params(ep) }
48
+ .ok(RapiTapir::Types.array(@schema))
49
+ .build
50
+
51
+ @endpoints << [endpoint_def, handler]
52
+ end
53
+
54
+ # Get specific resource (GET /resources/:id)
55
+ # @param options [Hash] Endpoint options
56
+ # @param handler [Proc] Request handler
57
+ def show(**options, &handler)
58
+ handler ||= proc { {} }
59
+
60
+ endpoint_def = @controller_class.GET("#{@base_path}/:id")
61
+ .summary(options[:summary] || "Get #{resource_name}")
62
+ .description(options[:description] || "Retrieve a specific #{resource_name} by ID")
63
+ .path_param(:id, :integer, description: "#{resource_name.capitalize} ID")
64
+ .ok(@schema)
65
+ .not_found(error_schema, description: "#{resource_name.capitalize} not found")
66
+ .build
67
+
68
+ @endpoints << [endpoint_def, handler]
69
+ end
70
+
71
+ # Create new resource (POST /resources)
72
+ # @param options [Hash] Endpoint options
73
+ # @param handler [Proc] Request handler
74
+ def create(**options, &handler)
75
+ handler ||= proc { {} }
76
+
77
+ endpoint_def = @controller_class.POST(@base_path)
78
+ .summary(options[:summary] || "Create #{resource_name}")
79
+ .description(options[:description] || "Create a new #{resource_name}")
80
+ .json_body(@schema)
81
+ .created(@schema)
82
+ .bad_request(validation_error_schema, description: 'Validation error')
83
+ .build
84
+
85
+ @endpoints << [endpoint_def, handler]
86
+ end
87
+
88
+ # Update resource (PUT /resources/:id)
89
+ # @param options [Hash] Endpoint options
90
+ # @param handler [Proc] Request handler
91
+ def update(**options, &handler)
92
+ handler ||= proc { {} }
93
+
94
+ endpoint_def = @controller_class.PUT("#{@base_path}/:id")
95
+ .summary(options[:summary] || "Update #{resource_name}")
96
+ .description(options[:description] || "Update an existing #{resource_name}")
97
+ .path_param(:id, RapiTapir::Types.integer, description: "#{resource_name.capitalize} ID")
98
+ .json_body(@schema)
99
+ .ok(@schema)
100
+ .not_found(error_schema, description: "#{resource_name.capitalize} not found")
101
+ .bad_request(validation_error_schema, description: 'Validation error')
102
+ .build
103
+
104
+ @endpoints << [endpoint_def, handler]
105
+ end
106
+
107
+ # Delete resource (DELETE /resources/:id)
108
+ # @param options [Hash] Endpoint options
109
+ # @param handler [Proc] Request handler
110
+ def destroy(**options, &handler)
111
+ handler ||= proc { head :no_content }
112
+
113
+ endpoint_def = @controller_class.DELETE("#{@base_path}/:id")
114
+ .summary(options[:summary] || "Delete #{resource_name}")
115
+ .description(options[:description] || "Delete a #{resource_name}")
116
+ .path_param(:id, :integer, description: "#{resource_name.capitalize} ID")
117
+ .no_content
118
+ .not_found(error_schema, description: "#{resource_name.capitalize} not found")
119
+ .build
120
+
121
+ @endpoints << [endpoint_def, handler]
122
+ end
123
+
124
+ # Add custom endpoint to the resource
125
+ # @param method [Symbol] HTTP method
126
+ # @param path_suffix [String] Path suffix to append to base path
127
+ # @param options [Hash] Endpoint options
128
+ # @param handler [Proc] Request handler
129
+ def custom(method, path_suffix, **options, &handler)
130
+ full_path = path_suffix.start_with?('/') ? path_suffix : "#{@base_path}/#{path_suffix}"
131
+
132
+ endpoint_def = @controller_class.public_send(method.to_s.upcase, full_path)
133
+ .summary(options[:summary] || "Custom #{method.upcase} #{path_suffix}")
134
+ .description(options[:description] || "Custom endpoint for #{resource_name}")
135
+
136
+ # Apply any custom configuration
137
+ endpoint_def = options[:configure].call(endpoint_def) if options[:configure]
138
+
139
+ endpoint_def = endpoint_def.build
140
+
141
+ @endpoints << [endpoint_def, handler]
142
+ end
143
+
144
+ private
145
+
146
+ # Add pagination query parameters to an endpoint
147
+ # @param endpoint [RapiTapir::DSL::FluentEndpointBuilder] The endpoint builder
148
+ # @return [RapiTapir::DSL::FluentEndpointBuilder] The modified endpoint builder
149
+ def add_pagination_params(endpoint)
150
+ endpoint.query(:limit, RapiTapir::Types.optional(RapiTapir::Types.integer(minimum: 1, maximum: 100)),
151
+ description: 'Maximum number of results')
152
+ .query(:offset, RapiTapir::Types.optional(RapiTapir::Types.integer(minimum: 0)),
153
+ description: 'Number of results to skip')
154
+ end
155
+
156
+ # Get the singular resource name from the base path
157
+ # @return [String] The singular resource name
158
+ def resource_name
159
+ @resource_name ||= @base_path.split('/').last.chomp('s')
160
+ end
161
+
162
+ # Standard error schema for 404 responses
163
+ # @return [RapiTapir::Types::Hash] Error schema
164
+ def error_schema
165
+ RapiTapir::Types.hash({
166
+ 'error' => RapiTapir::Types.string
167
+ })
168
+ end
169
+
170
+ # Validation error schema for 400 responses
171
+ # @return [RapiTapir::Types::Hash] Validation error schema
172
+ def validation_error_schema
173
+ RapiTapir::Types.hash({
174
+ 'error' => RapiTapir::Types.string,
175
+ 'details' => RapiTapir::Types.optional(RapiTapir::Types.array(RapiTapir::Types.string))
176
+ })
177
+ end
178
+ end
179
+ end
180
+ end
181
+ end
@@ -0,0 +1,114 @@
1
+ # frozen_string_literal: true
2
+
3
+ module RapiTapir
4
+ module Server
5
+ module Rails
6
+ # Rails routes integration module
7
+ # Provides helpers for automatically generating routes from RapiTapir endpoint definitions
8
+ module Routes
9
+ # Generate routes for a RapiTapir Rails controller
10
+ # @param controller_class [Class] The controller class with RapiTapir endpoints
11
+ # @example
12
+ # Rails.application.routes.draw do
13
+ # rapitapir_routes_for UsersController
14
+ # end
15
+ def rapitapir_routes_for(controller_class)
16
+ raise ArgumentError, "#{controller_class} must include RapiTapir::Server::Rails::Controller" unless controller_class.respond_to?(:rapitapir_endpoints)
17
+
18
+ controller_name = controller_class.controller_name
19
+
20
+ controller_class.rapitapir_endpoints.each do |action, endpoint_config|
21
+ endpoint_def = endpoint_config[:endpoint]
22
+ method = endpoint_def.method.downcase
23
+ path = convert_rapitapir_path_to_rails(endpoint_def.path)
24
+
25
+ # Generate the Rails route
26
+ public_send(method, path, to: "#{controller_name}##{action}",
27
+ as: route_name(controller_name, action, method))
28
+ end
29
+ end
30
+
31
+ # Generate all routes for multiple controllers
32
+ # @param controllers [Array<Class>] Array of controller classes
33
+ # @example
34
+ # Rails.application.routes.draw do
35
+ # rapitapir_routes_for_all [UsersController, BooksController, OrdersController]
36
+ # end
37
+ def rapitapir_routes_for_all(controllers)
38
+ controllers.each do |controller_class|
39
+ rapitapir_routes_for(controller_class)
40
+ end
41
+ end
42
+
43
+ # Auto-discover and register all RapiTapir controllers in the application
44
+ # @example
45
+ # Rails.application.routes.draw do
46
+ # rapitapir_auto_routes
47
+ # end
48
+ def rapitapir_auto_routes
49
+ # Find all controllers that include RapiTapir
50
+ controllers = ApplicationController.descendants.select do |klass|
51
+ klass.included_modules.include?(RapiTapir::Server::Rails::Controller) ||
52
+ klass < RapiTapir::Server::Rails::ControllerBase
53
+ end
54
+
55
+ rapitapir_routes_for_all(controllers)
56
+ end
57
+
58
+ private
59
+
60
+ # Convert RapiTapir path format to Rails route format
61
+ # @param rapitapir_path [String] Path with RapiTapir parameter syntax
62
+ # @return [String] Path with Rails parameter syntax
63
+ # @example
64
+ # convert_rapitapir_path_to_rails('/users/:id') # => '/users/:id'
65
+ # convert_rapitapir_path_to_rails('/users/{id}') # => '/users/:id'
66
+ def convert_rapitapir_path_to_rails(rapitapir_path)
67
+ # Convert {id} format to :id format for Rails
68
+ rapitapir_path.gsub(/\{(\w+)\}/, ':\1')
69
+ end
70
+
71
+ # Generate a route name for the endpoint
72
+ # @param controller_name [String] The controller name
73
+ # @param action [Symbol] The action name
74
+ # @param method [String] The HTTP method
75
+ # @return [Symbol] The route name
76
+ def route_name(controller_name, action, method)
77
+ base_name = controller_name.chomp('_controller')
78
+
79
+ case action
80
+ when :index
81
+ base_name.to_sym
82
+ when :show
83
+ singularize_name(base_name).to_sym
84
+ when :create
85
+ base_name.to_sym
86
+ when :update
87
+ singularize_name(base_name).to_sym
88
+ when :destroy
89
+ singularize_name(base_name).to_sym
90
+ else
91
+ :"#{method}_#{base_name}_#{action}"
92
+ end
93
+ end
94
+
95
+ # Simple singularization for route names
96
+ # @param name [String] The plural name
97
+ # @return [String] The singular name
98
+ def singularize_name(name)
99
+ # Simple singularization logic
100
+ if name.end_with?('ies')
101
+ "#{name.chomp('ies')}y"
102
+ elsif name.end_with?('s')
103
+ name.chomp('s')
104
+ else
105
+ name
106
+ end
107
+ end
108
+ end
109
+ end
110
+ end
111
+ end
112
+
113
+ # NOTE: Rails routes extension is handled in the rails_integration.rb file
114
+ # to ensure proper timing with Rails application initialization
@@ -3,15 +3,22 @@
3
3
  require_relative 'rails_controller'
4
4
  require_relative 'rails_adapter_class'
5
5
 
6
+ # Load enhanced Rails integration components
7
+ require_relative 'rails/controller_base'
8
+ require_relative 'rails/configuration'
9
+ require_relative 'rails/routes'
10
+ require_relative 'rails/resource_builder'
11
+ require_relative 'rails/documentation_helpers'
12
+
6
13
  module RapiTapir
7
14
  module Server
8
15
  # Rails integration module for RapiTapir
9
16
  #
10
17
  # Provides controller concerns and adapters for seamless integration with Rails applications.
11
- # Split into separate files for better organization while maintaining compatibility.
18
+ # Includes the enhanced Rails integration with ControllerBase and auto-routing.
12
19
  module Rails
13
- # Main module that includes both Controller concern and RailsAdapter class
14
- # This maintains backward compatibility while organizing code better
20
+ # Main module that includes both legacy Controller concern and enhanced ControllerBase
21
+ # This maintains backward compatibility while providing the new enhanced features
15
22
  end
16
23
  end
17
24
  end
@@ -13,9 +13,7 @@ module RapiTapir
13
13
 
14
14
  # Register an endpoint and generate Rails routes
15
15
  def register_endpoint(endpoint, controller_class, action_name)
16
- unless endpoint.is_a?(RapiTapir::Core::Endpoint)
17
- raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint'
18
- end
16
+ raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint' unless endpoint.is_a?(RapiTapir::Core::Endpoint)
19
17
 
20
18
  endpoint.validate!
21
19
 
@@ -19,9 +19,7 @@ module RapiTapir
19
19
  class_methods do
20
20
  # Register an endpoint for this controller
21
21
  def rapitapir_endpoint(action_name, endpoint, &handler)
22
- unless endpoint.is_a?(RapiTapir::Core::Endpoint)
23
- raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint'
24
- end
22
+ raise ArgumentError, 'Endpoint must be a RapiTapir::Core::Endpoint' unless endpoint.is_a?(RapiTapir::Core::Endpoint)
25
23
 
26
24
  endpoint.validate!
27
25
 
@@ -0,0 +1,67 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Rails integration loader - ensures proper module initialization
4
+ # Only loads if Rails and ActiveSupport are available
5
+
6
+ # First, ensure the module structure exists
7
+ module RapiTapir
8
+ module Server
9
+ module Rails
10
+ # Rails integration module for RapiTapir
11
+ end
12
+ end
13
+
14
+ # Define a method to load Rails integration when Rails becomes available
15
+ def self.load_rails_integration!
16
+ return if @rails_integration_loaded
17
+ return unless defined?(Rails) && defined?(ActiveSupport)
18
+
19
+ # Remove fallback ControllerBase if it exists
20
+ RapiTapir::Server::Rails.send(:remove_const, :ControllerBase) if RapiTapir::Server::Rails.const_defined?(:ControllerBase)
21
+
22
+ # Load Rails integration components in the correct order
23
+ require_relative 'rails_controller'
24
+ require_relative 'rails_adapter_class'
25
+ require_relative 'rails/configuration'
26
+ require_relative 'rails/routes'
27
+ require_relative 'rails/resource_builder'
28
+ require_relative 'rails/documentation_helpers'
29
+ require_relative 'rails/controller_base'
30
+
31
+ # Create Railtie for Rails integration
32
+ if defined?(Rails::Railtie) && !Object.const_defined?(:RapiTapirRailtie)
33
+ Object.const_set(:RapiTapirRailtie, Class.new(Rails::Railtie) do
34
+ initializer 'rapitapir.extend_routes', after: :initialize_routes do |app|
35
+ app.routes&.extend(RapiTapir::Server::Rails::Routes)
36
+ end
37
+ end)
38
+ end
39
+
40
+ @rails_integration_loaded = true
41
+ end
42
+ end
43
+
44
+ # Load immediately if Rails is already available
45
+ if defined?(Rails) && defined?(ActiveSupport)
46
+ RapiTapir.load_rails_integration!
47
+ else
48
+ # Rails not available - provide minimal fallback
49
+ module RapiTapir
50
+ module Server
51
+ module Rails
52
+ class ControllerBase
53
+ def self.method_missing(method, ...)
54
+ # Try to load Rails integration when accessed
55
+ RapiTapir.load_rails_integration!
56
+ if defined?(RapiTapir::Server::Rails::ControllerBase) && self.class != RapiTapir::Server::Rails::ControllerBase
57
+ return RapiTapir::Server::Rails::ControllerBase.send(method, ...)
58
+ end
59
+
60
+ raise NameError,
61
+ 'Rails integration not available. Please ensure Rails is loaded before requiring RapiTapir.'
62
+ end
63
+ end
64
+ end
65
+ end
66
+ end
67
+ end