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,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
|
-
#
|
|
18
|
+
# Includes the enhanced Rails integration with ControllerBase and auto-routing.
|
|
12
19
|
module Rails
|
|
13
|
-
# Main module that includes both Controller concern and
|
|
14
|
-
# This maintains backward compatibility while
|
|
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
|