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
data/examples/user_api.rb CHANGED
@@ -5,180 +5,178 @@ require_relative '../lib/rapitapir'
5
5
 
6
6
  # Example: User Management API
7
7
  module UserAPI
8
- extend RapiTapir::DSL
8
+ # Shared type definitions
9
+ USER_TYPE = RapiTapir::Types.hash({
10
+ 'id' => RapiTapir::Types.integer,
11
+ 'name' => RapiTapir::Types.string,
12
+ 'email' => RapiTapir::Types.string
13
+ })
14
+
15
+ USER_DETAIL_TYPE = RapiTapir::Types.hash({
16
+ 'id' => RapiTapir::Types.integer,
17
+ 'name' => RapiTapir::Types.string,
18
+ 'email' => RapiTapir::Types.string,
19
+ 'created_at' => RapiTapir::Types.datetime
20
+ })
21
+
22
+ CREATE_USER_TYPE = RapiTapir::Types.hash({
23
+ 'name' => RapiTapir::Types.string,
24
+ 'email' => RapiTapir::Types.string,
25
+ 'password' => RapiTapir::Types.string
26
+ })
27
+
28
+ LOGIN_TYPE = RapiTapir::Types.hash({
29
+ 'email' => RapiTapir::Types.string,
30
+ 'password' => RapiTapir::Types.string
31
+ })
32
+
33
+ LOGIN_RESULT_TYPE = RapiTapir::Types.hash({
34
+ 'user' => USER_TYPE,
35
+ 'token' => RapiTapir::Types.string,
36
+ 'expires_at' => RapiTapir::Types.datetime
37
+ })
38
+
39
+ ERROR_TYPE = RapiTapir::Types.hash({
40
+ 'error' => RapiTapir::Types.string
41
+ })
42
+
43
+ VALIDATION_ERROR_TYPE = RapiTapir::Types.hash({
44
+ 'error' => RapiTapir::Types.string,
45
+ 'validation_errors' => RapiTapir::Types.array(
46
+ RapiTapir::Types.hash({
47
+ 'field' => RapiTapir::Types.string,
48
+ 'message' => RapiTapir::Types.string
49
+ })
50
+ )
51
+ })
52
+
53
+ USER_LIST_TYPE = RapiTapir::Types.hash({
54
+ 'users' => RapiTapir::Types.array(USER_TYPE),
55
+ 'total' => RapiTapir::Types.integer,
56
+ 'page' => RapiTapir::Types.integer,
57
+ 'limit' => RapiTapir::Types.integer
58
+ })
9
59
 
10
60
  # GET /users - List all users
11
61
  LIST_USERS = RapiTapir.get('/users')
12
- .in(query(:page, :integer, optional: true))
13
- .in(query(:limit, :integer, optional: true))
14
- .in(query(:search, :string, optional: true))
15
- .in(header(:authorization, :string))
16
- .out(status_code(200))
17
- .out(json_body({
18
- users: [{ id: :integer, name: :string, email: :string }],
19
- total: :integer,
20
- page: :integer,
21
- limit: :integer
22
- }))
23
- .error_out(401, json_body({ error: :string }))
24
- .error_out(500, json_body({ error: :string }))
62
+ .query(:page, RapiTapir::Types.optional(RapiTapir::Types.integer))
63
+ .query(:limit, RapiTapir::Types.optional(RapiTapir::Types.integer))
64
+ .query(:search, RapiTapir::Types.optional(RapiTapir::Types.string))
65
+ .header(:authorization, RapiTapir::Types.string)
66
+ .ok(USER_LIST_TYPE)
67
+ .unauthorized(ERROR_TYPE)
68
+ .internal_server_error(ERROR_TYPE)
25
69
  .description('Retrieve a paginated list of users')
26
70
  .summary('List users')
27
- .tag('users')
71
+ .tags('users')
72
+ .build
28
73
 
29
74
  # GET /users/:id - Get specific user
30
75
  GET_USER = RapiTapir.get('/users/:id')
31
- .in(path_param(:id, :integer))
32
- .in(header(:authorization, :string))
33
- .out(status_code(200))
34
- .out(json_body({ id: :integer, name: :string, email: :string, created_at: :datetime }))
35
- .error_out(401, json_body({ error: :string }))
36
- .error_out(404, json_body({ error: :string }))
37
- .error_out(500, json_body({ error: :string }))
76
+ .path_param(:id, RapiTapir::Types.integer)
77
+ .header(:authorization, RapiTapir::Types.string)
78
+ .ok(USER_DETAIL_TYPE)
79
+ .unauthorized(ERROR_TYPE)
80
+ .not_found(ERROR_TYPE)
81
+ .internal_server_error(ERROR_TYPE)
38
82
  .description('Retrieve a specific user by ID')
39
83
  .summary('Get user')
40
- .tag('users')
84
+ .tags('users')
85
+ .build
41
86
 
42
87
  # POST /users - Create new user
43
88
  CREATE_USER = RapiTapir.post('/users')
44
- .in(header(:authorization, :string))
45
- .in(header(:'content-type', :string))
46
- .in(body({ name: :string, email: :string, password: :string }))
47
- .out(status_code(201))
48
- .out(json_body({ id: :integer, name: :string, email: :string, created_at: :datetime }))
49
- .error_out(400, json_body({ error: :string, details: :string }))
50
- .error_out(401, json_body({ error: :string }))
51
- .error_out(422, json_body({ error: :string,
52
- validation_errors: [{ field: :string, message: :string }] }))
53
- .error_out(500, json_body({ error: :string }))
89
+ .header(:authorization, RapiTapir::Types.string)
90
+ .json_body(CREATE_USER_TYPE)
91
+ .created(USER_DETAIL_TYPE)
92
+ .bad_request(ERROR_TYPE)
93
+ .unauthorized(ERROR_TYPE)
94
+ .unprocessable_entity(VALIDATION_ERROR_TYPE)
95
+ .internal_server_error(ERROR_TYPE)
54
96
  .description('Create a new user account')
55
97
  .summary('Create user')
56
- .tag('users')
98
+ .tags('users')
99
+ .build
57
100
 
58
101
  # PUT /users/:id - Update user
59
102
  UPDATE_USER = RapiTapir.put('/users/:id')
60
- .in(path_param(:id, :integer))
61
- .in(header(:authorization, :string))
62
- .in(header(:'content-type', :string))
63
- .in(body({ name: :string, email: :string }))
64
- .out(status_code(200))
65
- .out(json_body({ id: :integer, name: :string, email: :string, updated_at: :datetime }))
66
- .error_out(400, json_body({ error: :string, details: :string }))
67
- .error_out(401, json_body({ error: :string }))
68
- .error_out(404, json_body({ error: :string }))
69
- .error_out(422, json_body({ error: :string,
70
- validation_errors: [{ field: :string, message: :string }] }))
71
- .error_out(500, json_body({ error: :string }))
103
+ .path_param(:id, RapiTapir::Types.integer)
104
+ .header(:authorization, RapiTapir::Types.string)
105
+ .json_body(RapiTapir::Types.hash({
106
+ 'name' => RapiTapir::Types.string,
107
+ 'email' => RapiTapir::Types.string
108
+ }))
109
+ .ok(RapiTapir::Types.hash({
110
+ 'id' => RapiTapir::Types.integer,
111
+ 'name' => RapiTapir::Types.string,
112
+ 'email' => RapiTapir::Types.string,
113
+ 'updated_at' => RapiTapir::Types.datetime
114
+ }))
115
+ .bad_request(ERROR_TYPE)
116
+ .unauthorized(ERROR_TYPE)
117
+ .not_found(ERROR_TYPE)
118
+ .unprocessable_entity(VALIDATION_ERROR_TYPE)
119
+ .internal_server_error(ERROR_TYPE)
72
120
  .description('Update an existing user')
73
121
  .summary('Update user')
74
- .tag('users')
122
+ .tags('users')
123
+ .build
75
124
 
76
125
  # DELETE /users/:id - Delete user
77
126
  DELETE_USER = RapiTapir.delete('/users/:id')
78
- .in(path_param(:id, :integer))
79
- .in(header(:authorization, :string))
80
- .out(status_code(204))
81
- .error_out(401, json_body({ error: :string }))
82
- .error_out(404, json_body({ error: :string }))
83
- .error_out(500, json_body({ error: :string }))
127
+ .path_param(:id, RapiTapir::Types.integer)
128
+ .header(:authorization, RapiTapir::Types.string)
129
+ .no_content
130
+ .unauthorized(ERROR_TYPE)
131
+ .not_found(ERROR_TYPE)
132
+ .internal_server_error(ERROR_TYPE)
84
133
  .description('Delete a user account')
85
134
  .summary('Delete user')
86
- .tag('users')
135
+ .tags('users')
136
+ .build
87
137
 
88
138
  # POST /users/login - User authentication
89
139
  LOGIN_USER = RapiTapir.post('/users/login')
90
- .in(header(:'content-type', :string))
91
- .in(body({ email: :string, password: :string }))
92
- .out(status_code(200))
93
- .out(json_body({
94
- user: { id: :integer, name: :string, email: :string },
95
- token: :string,
96
- expires_at: :datetime
97
- }))
98
- .error_out(400, json_body({ error: :string }))
99
- .error_out(401, json_body({ error: :string }))
100
- .error_out(500, json_body({ error: :string }))
140
+ .json_body(LOGIN_TYPE)
141
+ .ok(LOGIN_RESULT_TYPE)
142
+ .bad_request(ERROR_TYPE)
143
+ .unauthorized(ERROR_TYPE)
144
+ .internal_server_error(ERROR_TYPE)
101
145
  .description('Authenticate user and return access token')
102
146
  .summary('User login')
103
- .tag('authentication')
147
+ .tags('authentication')
148
+ .build
104
149
 
105
150
  # Example usage and validation
106
151
  def self.demo
107
152
  puts '=== RapiTapir User API Demo ==='
108
153
  puts
109
154
 
110
- # Example 1: Valid user creation
111
- puts '1. Valid user creation:'
112
- input_data = {
113
- body: { name: 'John Doe', email: 'john@example.com', password: 'secret123' }
114
- }
115
- output_data = {
116
- id: 1,
117
- name: 'John Doe',
118
- email: 'john@example.com',
119
- created_at: DateTime.now
120
- }
121
-
122
- begin
123
- CREATE_USER.validate!(input_data, output_data)
124
- puts 'āœ“ Validation passed'
125
- rescue StandardError => e
126
- puts "āœ— Validation failed: #{e.message}"
127
- end
155
+ # Example 1: Endpoint structure
156
+ puts '1. Endpoint structure:'
157
+ puts ' GET /users:'
158
+ puts " Method: #{LIST_USERS.method} #{LIST_USERS.path}"
159
+ puts " Inputs: #{LIST_USERS.inputs.length}"
160
+ puts " Outputs: #{LIST_USERS.outputs.length}"
161
+ puts " Error responses: #{LIST_USERS.errors.length}"
128
162
  puts
129
163
 
130
- # Example 2: Invalid user creation (missing required field)
131
- puts '2. Invalid user creation (missing password):'
132
- invalid_input = {
133
- body: { name: 'John Doe', email: 'john@example.com' }
134
- }
135
-
136
- begin
137
- CREATE_USER.validate!(invalid_input, output_data)
138
- puts 'āœ“ Validation passed'
139
- rescue StandardError => e
140
- puts "āœ— Validation failed: #{e.message}"
141
- end
164
+ # Example 2: Endpoint metadata
165
+ puts '2. Endpoint metadata:'
166
+ puts " Summary: #{GET_USER.metadata[:summary]}"
167
+ puts " Description: #{GET_USER.metadata[:description]}"
142
168
  puts
143
169
 
144
- # Example 3: Valid user listing
145
- puts '3. Valid user listing:'
146
- list_input = {}
147
- list_output = {
148
- users: [
149
- { id: 1, name: 'John Doe', email: 'john@example.com' },
150
- { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
151
- ],
152
- total: 2,
153
- page: 1,
154
- limit: 10
155
- }
156
-
157
- begin
158
- LIST_USERS.validate!(list_input, list_output)
159
- puts 'āœ“ Validation passed'
160
- rescue StandardError => e
161
- puts "āœ— Validation failed: #{e.message}"
162
- end
163
- puts
170
+ # Example 3: Built-in validation
171
+ puts '3. Endpoint validation:'
172
+ CREATE_USER.validate!
173
+ puts ' CREATE_USER passed built-in validation āœ“'
164
174
 
165
- # Example 4: Endpoint metadata
166
- puts '4. Endpoint metadata:'
167
- puts 'GET /users:'
168
- puts " Description: #{GET_USER.metadata[:description]}"
169
- puts " Summary: #{GET_USER.metadata[:summary]}"
170
- puts " Tag: #{GET_USER.metadata[:tag]}"
171
- puts " Inputs: #{GET_USER.inputs.length}"
172
- puts " Outputs: #{GET_USER.outputs.length}"
173
- puts " Error responses: #{GET_USER.errors.length}"
175
+ # Example 4: All endpoints summary
174
176
  puts
175
-
176
- # Example 5: Serialization
177
- puts '5. Output serialization:'
178
- json_output = CREATE_USER.outputs.find { |o| o.kind == :json }
179
- if json_output
180
- serialized = json_output.serialize(output_data)
181
- puts "JSON: #{serialized}"
177
+ puts '4. All endpoints:'
178
+ [LIST_USERS, GET_USER, CREATE_USER, UPDATE_USER, DELETE_USER, LOGIN_USER].each do |ep|
179
+ puts " #{ep.method.to_s.ljust(6).upcase} #{ep.path}"
182
180
  end
183
181
  puts
184
182
 
@@ -0,0 +1,173 @@
1
+ # frozen_string_literal: true
2
+
3
+ # RapiTapir Validation Error Examples
4
+ #
5
+ # This file demonstrates the improved validation error messages in RapiTapir v2.0
6
+ # Run this script to see the enhanced developer experience for API validation.
7
+
8
+ require_relative '../lib/rapitapir'
9
+
10
+ puts "šŸ” RapiTapir v2.0 - Enhanced Validation Error Messages"
11
+ puts "=" * 60
12
+
13
+ # Define a realistic API schema
14
+ USER_SCHEMA = RapiTapir::Types.hash({
15
+ 'name' => RapiTapir::Types.string(min_length: 2, max_length: 50),
16
+ 'email' => RapiTapir::Types.email,
17
+ 'age' => RapiTapir::Types.integer(minimum: 18, maximum: 120),
18
+ 'profile' => RapiTapir::Types.hash({
19
+ 'bio' => RapiTapir::Types.string(max_length: 200),
20
+ 'website' => RapiTapir::Types.string(format: :uri),
21
+ 'newsletter' => RapiTapir::Types.boolean
22
+ })
23
+ })
24
+
25
+ def show_validation_example(title, data, schema = USER_SCHEMA)
26
+ puts "\n#{title}"
27
+ puts "-" * 40
28
+ puts "šŸ“„ Input: #{data.inspect}"
29
+
30
+ begin
31
+ # First try coercion (type conversion + missing field checks)
32
+ coerced = schema.coerce(data)
33
+
34
+ # Then validate the coerced data (constraint checks)
35
+ validation_result = schema.validate(coerced)
36
+
37
+ if validation_result[:valid]
38
+ puts "āœ… Success: #{coerced.inspect}"
39
+ else
40
+ puts "āŒ Validation Failed: #{validation_result[:errors].first}"
41
+ puts "šŸ“‹ All errors: #{validation_result[:errors].join(', ')}"
42
+ end
43
+
44
+ rescue RapiTapir::Types::CoercionError => e
45
+ puts "āŒ Coercion Error: #{e.message}"
46
+ puts "šŸŽÆ Field: #{extract_field_from_error(e)}" if extract_field_from_error(e)
47
+ puts "šŸ“‹ Expected: #{e.type}"
48
+ puts "šŸ’­ Received: #{e.value.inspect}"
49
+ end
50
+ end
51
+
52
+ def extract_field_from_error(error)
53
+ if error.reason =~ /Field '([^']+)':/
54
+ $1
55
+ elsif error.reason =~ /Required field '([^']+)'/
56
+ $1
57
+ else
58
+ nil
59
+ end
60
+ end
61
+
62
+ # Example 1: Missing required field
63
+ show_validation_example(
64
+ "1ļøāƒ£ Missing Required Field",
65
+ {
66
+ 'name' => 'John Doe',
67
+ 'age' => 25,
68
+ 'profile' => {
69
+ 'bio' => 'Software developer',
70
+ 'newsletter' => true
71
+ }
72
+ # Missing 'email' field
73
+ }
74
+ )
75
+
76
+ # Example 2: Invalid email format
77
+ show_validation_example(
78
+ "2ļøāƒ£ Invalid Email Format",
79
+ {
80
+ 'name' => 'John Doe',
81
+ 'email' => 'not-an-email',
82
+ 'age' => 25,
83
+ 'profile' => {
84
+ 'bio' => 'Software developer',
85
+ 'website' => 'https://example.com',
86
+ 'newsletter' => true
87
+ }
88
+ }
89
+ )
90
+
91
+ # Example 3: Age constraint violation
92
+ show_validation_example(
93
+ "3ļøāƒ£ Age Constraint Violation",
94
+ {
95
+ 'name' => 'John Doe',
96
+ 'email' => 'john@example.com',
97
+ 'age' => 16, # Under 18
98
+ 'profile' => {
99
+ 'bio' => 'High school student',
100
+ 'website' => 'https://example.com',
101
+ 'newsletter' => false
102
+ }
103
+ }
104
+ )
105
+
106
+ # Example 4: Invalid nested field
107
+ show_validation_example(
108
+ "4ļøāƒ£ Invalid Nested Field",
109
+ {
110
+ 'name' => 'John Doe',
111
+ 'email' => 'john@example.com',
112
+ 'age' => 25,
113
+ 'profile' => {
114
+ 'bio' => 'Software developer',
115
+ 'website' => 'not-a-valid-url',
116
+ 'newsletter' => 'yes' # Should be boolean
117
+ }
118
+ }
119
+ )
120
+
121
+ # Example 5: Missing nested required field
122
+ show_validation_example(
123
+ "5ļøāƒ£ Missing Nested Required Field",
124
+ {
125
+ 'name' => 'John Doe',
126
+ 'email' => 'john@example.com',
127
+ 'age' => 25,
128
+ 'profile' => {
129
+ 'bio' => 'Software developer',
130
+ 'website' => 'https://example.com'
131
+ # Missing 'newsletter' field
132
+ }
133
+ }
134
+ )
135
+
136
+ # Example 6: String length validation
137
+ show_validation_example(
138
+ "6ļøāƒ£ String Length Validation",
139
+ {
140
+ 'name' => 'J', # Too short (min 2 chars)
141
+ 'email' => 'john@example.com',
142
+ 'age' => 25,
143
+ 'profile' => {
144
+ 'bio' => 'A' * 250, # Too long (max 200 chars)
145
+ 'website' => 'https://example.com',
146
+ 'newsletter' => true
147
+ }
148
+ }
149
+ )
150
+
151
+ # Example 7: Successful validation
152
+ show_validation_example(
153
+ "7ļøāƒ£ Successful Validation ✨",
154
+ {
155
+ 'name' => 'John Doe',
156
+ 'email' => 'john@example.com',
157
+ 'age' => 25,
158
+ 'profile' => {
159
+ 'bio' => 'Software developer passionate about APIs',
160
+ 'website' => 'https://johndoe.dev',
161
+ 'newsletter' => true
162
+ }
163
+ }
164
+ )
165
+
166
+ puts "\nšŸŽ‰ Enhanced Error Messages Summary:"
167
+ puts " āœ… Specific field names in error messages"
168
+ puts " āœ… Clear indication of missing vs invalid fields"
169
+ puts " āœ… Expected vs received value information"
170
+ puts " āœ… Nested object validation with field context"
171
+ puts " āœ… Constraint violation details (length, format, etc.)"
172
+ puts " āœ… Maintains backward compatibility"
173
+ puts "\nšŸ’” This improves the developer experience by providing actionable feedback!"