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/docs/using-mcp.md ADDED
@@ -0,0 +1,93 @@
1
+ # Using RapiTapir APIs as LLM Tools (MCP)
2
+
3
+ RapiTapir supports the Model Context Protocol (MCP) to make your API endpoints discoverable and consumable by LLMs and AI agents.
4
+
5
+ ### How to Mark Endpoints for MCP Export
6
+
7
+ Use the `.mcp_export` method in your endpoint DSL chain:
8
+
9
+ ```ruby
10
+ endpoint(
11
+ GET('/hello')
12
+ .query(:name, T.string, description: 'Name to greet')
13
+ .ok(T.hash({ "message" => T.string }))
14
+ .enable_mcp # Mark for MCP export
15
+ .build
16
+ ) do |inputs|
17
+ { message: "Hello, #{inputs[:name]}!" }
18
+ end
19
+ ```
20
+
21
+ ### CLI Usage
22
+
23
+ Generate MCP context using the command line:
24
+
25
+ ```bash
26
+ # Generate MCP context for all marked endpoints
27
+ rapitapir generate mcp --endpoints api.rb --output mcp-context.json
28
+
29
+ # Alternative export command
30
+ rapitapir export mcp --endpoints api.rb --output mcp-context.json
31
+ ```
32
+
33
+ ### Ruby API Usage
34
+
35
+ Use the MCP exporter directly in Ruby code:
36
+
37
+ ```ruby
38
+ require 'rapitapir/ai/mcp'
39
+
40
+ # Load your endpoints
41
+ endpoints = [your_endpoint_list]
42
+
43
+ # Create exporter and generate context
44
+ exporter = RapiTapir::AI::MCP::Exporter.new(endpoints)
45
+ mcp_context = exporter.as_mcp_context
46
+
47
+ # Save to file
48
+ File.write('mcp-context.json', JSON.pretty_generate(mcp_context))
49
+ ```
50
+
51
+ ### Example Output
52
+
53
+ The generated MCP context includes:
54
+
55
+ ```json
56
+ {
57
+ "name": "RapiTapir API Context",
58
+ "version": "1.0.0",
59
+ "endpoints": [
60
+ {
61
+ "name": "get__users__id_",
62
+ "method": "GET",
63
+ "path": "/users/{id}",
64
+ "summary": "Retrieve a user by ID",
65
+ "description": "Fetches a single user record by their unique identifier",
66
+ "input_schema": {
67
+ "id": {
68
+ "type": "integer",
69
+ "kind": "path",
70
+ "required": true
71
+ }
72
+ },
73
+ "output_schema": {
74
+ "json": {
75
+ "type": {
76
+ "id": "integer",
77
+ "name": "string",
78
+ "email": "string"
79
+ }
80
+ }
81
+ },
82
+ "examples": []
83
+ }
84
+ ]
85
+ }
86
+ ```
87
+
88
+ ### Use Cases
89
+ - LLM/agent tool discovery
90
+ - Automated API documentation for AI
91
+ - Integration with agent frameworks (LangChain, OpenAI, etc.)
92
+
93
+ See the AI integration plan for more details.
@@ -0,0 +1,83 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'bundler/setup'
4
+
5
+ # Add the project root to the load path for development
6
+ project_root = File.expand_path('../../', __dir__)
7
+ $LOAD_PATH.unshift(File.join(project_root, 'lib')) unless $LOAD_PATH.include?(File.join(project_root, 'lib'))
8
+
9
+ require 'rapitapir'
10
+ require 'rapitapir/ai/rag'
11
+ require 'json'
12
+
13
+ # Example: Knowledge Base API with RAG Support
14
+ module KnowledgeBaseAPI
15
+ extend RapiTapir::DSL
16
+
17
+ # Type alias for convenience
18
+ T = RapiTapir::Types
19
+
20
+ # Define schemas
21
+ ASK_SCHEMA = T.hash({
22
+ 'question' => T.string,
23
+ 'user_id' => T.string
24
+ }).freeze
25
+
26
+ ANSWER_SCHEMA = T.hash({
27
+ 'answer' => T.string,
28
+ 'sources' => T.array(T.string),
29
+ 'timestamp' => T.string
30
+ }).freeze
31
+
32
+ CHAT_INPUT_SCHEMA = T.hash({
33
+ 'message' => T.string
34
+ }).freeze
35
+
36
+ CHAT_OUTPUT_SCHEMA = T.hash({
37
+ 'response' => T.string
38
+ }).freeze
39
+
40
+ # Ask a question using RAG
41
+ ASK_QUESTION = RapiTapir.post('/ask')
42
+ .json_body(ASK_SCHEMA)
43
+ .ok(ANSWER_SCHEMA)
44
+ .rag_inference(
45
+ llm: :openai,
46
+ retrieval: :memory,
47
+ context_fields: [:user_id],
48
+ config: {
49
+ llm: { api_key: 'mock' },
50
+ retrieval: {
51
+ documents: [
52
+ { content: 'RapiTapir is a Ruby API framework that provides type-safe endpoints.' },
53
+ { content: 'RAG combines document retrieval with LLM text generation.' },
54
+ { content: 'This API demonstrates AI-powered question answering.' }
55
+ ]
56
+ }
57
+ }
58
+ )
59
+ .summary('Ask a question about the knowledge base')
60
+ .mcp_export
61
+
62
+ # Simple chat
63
+ CHAT = RapiTapir.post('/chat')
64
+ .json_body(CHAT_INPUT_SCHEMA)
65
+ .ok(CHAT_OUTPUT_SCHEMA)
66
+ .rag_inference(
67
+ llm: :openai,
68
+ retrieval: :memory,
69
+ config: {
70
+ llm: { api_key: 'mock' },
71
+ retrieval: {
72
+ documents: [
73
+ { content: 'RapiTapir supports MCP for AI agent integration.' }
74
+ ]
75
+ }
76
+ }
77
+ )
78
+ .summary('Chat with AI')
79
+ .mcp_export
80
+ end
81
+
82
+ # Endpoints for CLI
83
+ knowledge_base_api = [KnowledgeBaseAPI::ASK_QUESTION, KnowledgeBaseAPI::CHAT]
@@ -0,0 +1,92 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative '../../lib/rapitapir'
4
+ require_relative '../../lib/rapitapir/endpoint_registry'
5
+
6
+ # Example: User Management API with MCP Export
7
+ # This demonstrates how to mark endpoints for MCP export for AI/LLM consumption
8
+
9
+ class UserManagementAPI
10
+ include RapiTapir::DSL
11
+
12
+ # User schema for consistent typing
13
+ USER_SCHEMA = {
14
+ id: :integer,
15
+ name: :string,
16
+ email: :string,
17
+ created_at: :datetime
18
+ }.freeze
19
+
20
+ # Endpoint 1: Get user by ID - marked for MCP export
21
+ GET_USER = RapiTapir.get('/users/{id}')
22
+ .in(path_param(:id, :integer))
23
+ .out(json_body(USER_SCHEMA))
24
+ .summary('Retrieve a user by ID')
25
+ .description('Fetches a single user record by their unique identifier')
26
+ .mcp_export # Mark for MCP export
27
+
28
+ # Endpoint 2: Create new user - marked for MCP export
29
+ CREATE_USER = RapiTapir.post('/users')
30
+ .in(json_body({
31
+ name: :string,
32
+ email: :string
33
+ }))
34
+ .out(status_code(201))
35
+ .out(json_body(USER_SCHEMA))
36
+ .summary('Create a new user')
37
+ .description('Creates a new user account with name and email')
38
+ .mcp_export # Mark for MCP export
39
+
40
+ # Endpoint 3: Update user - NOT marked for MCP export
41
+ UPDATE_USER = RapiTapir.put('/users/{id}')
42
+ .in(path_param(:id, :integer))
43
+ .in(json_body({
44
+ name: :string,
45
+ email: :string
46
+ }))
47
+ .out(json_body(USER_SCHEMA))
48
+ .summary('Update an existing user')
49
+ .description('Updates user information')
50
+ # No .mcp_export - this endpoint won't be included in MCP context
51
+
52
+ # Endpoint 4: List users with pagination - marked for MCP export
53
+ LIST_USERS = RapiTapir.get('/users')
54
+ .in(query(:page, :integer, required: false))
55
+ .in(query(:limit, :integer, required: false))
56
+ .out(json_body({
57
+ users: [:array, USER_SCHEMA],
58
+ total: :integer,
59
+ page: :integer,
60
+ limit: :integer
61
+ }))
62
+ .summary('List all users')
63
+ .description('Retrieves a paginated list of all users')
64
+ .mcp_export # Mark for MCP export
65
+
66
+ # Store endpoints for export
67
+ ALL_ENDPOINTS = [GET_USER, CREATE_USER, UPDATE_USER, LIST_USERS].freeze
68
+
69
+ # Register endpoints in global registry
70
+ RapiTapir::EndpointRegistry.register_all(ALL_ENDPOINTS)
71
+ end
72
+
73
+ # Usage demonstration
74
+ if __FILE__ == $PROGRAM_NAME
75
+ puts "User Management API Example"
76
+ puts "==========================="
77
+
78
+ # Show which endpoints are marked for MCP export
79
+ mcp_endpoints = UserManagementAPI::ALL_ENDPOINTS.select(&:mcp_export?)
80
+ puts "\nEndpoints marked for MCP export:"
81
+ mcp_endpoints.each do |ep|
82
+ puts "- #{ep.method.upcase} #{ep.path} (#{ep.metadata[:summary]})"
83
+ end
84
+
85
+ # Generate MCP context
86
+ require_relative '../../lib/rapitapir/ai/mcp'
87
+ exporter = RapiTapir::AI::MCP::Exporter.new(UserManagementAPI::ALL_ENDPOINTS)
88
+ mcp_context = exporter.as_mcp_context
89
+
90
+ puts "\nGenerated MCP Context:"
91
+ puts JSON.pretty_generate(mcp_context)
92
+ end
@@ -0,0 +1,187 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'bundler/setup'
4
+
5
+ # Add the project root to the load path for development
6
+ project_root = File.expand_path('../../', __dir__)
7
+ $LOAD_PATH.unshift(File.join(project_root, 'lib')) unless $LOAD_PATH.include?(File.join(project_root, 'lib'))
8
+
9
+ require 'rapitapir'
10
+ require 'rapitapir/ai/llm_instruction'
11
+ require 'json'
12
+
13
+ # Type alias for convenience (avoid warning if already defined)
14
+ T = RapiTapir::Types unless defined?(T)
15
+
16
+ module UserValidationAPI
17
+ # User creation validation schema
18
+ USER_INPUT_SCHEMA = T.hash({
19
+ 'name' => T.string(min_length: 2, max_length: 50),
20
+ 'email' => T.email,
21
+ 'age' => T.integer(minimum: 18, maximum: 120),
22
+ 'preferences' => T.optional(T.hash({
23
+ 'newsletter' => T.boolean,
24
+ 'notifications' => T.boolean
25
+ }))
26
+ }).freeze
27
+
28
+ USER_OUTPUT_SCHEMA = T.hash({
29
+ 'id' => T.integer,
30
+ 'name' => T.string,
31
+ 'email' => T.string,
32
+ 'status' => T.string,
33
+ 'created_at' => T.datetime
34
+ }).freeze
35
+
36
+ VALIDATION_ERROR_SCHEMA = T.hash({
37
+ 'error' => T.string,
38
+ 'field_errors' => T.array(T.hash({
39
+ 'field' => T.string,
40
+ 'message' => T.string,
41
+ 'code' => T.string
42
+ }))
43
+ }).freeze
44
+
45
+ # Data transformation schemas
46
+ LEGACY_USER_INPUT = T.hash({
47
+ 'full_name' => T.string,
48
+ 'email_address' => T.string,
49
+ 'birth_year' => T.integer,
50
+ 'settings' => T.optional(T.string) # JSON string in legacy format
51
+ }).freeze
52
+
53
+ # Analytics schema
54
+ USER_ANALYTICS_SCHEMA = T.hash({
55
+ 'user_count' => T.integer,
56
+ 'active_users' => T.integer,
57
+ 'signup_rate' => T.float,
58
+ 'demographics' => T.hash({
59
+ 'avg_age' => T.float,
60
+ 'age_distribution' => T.array(T.hash({
61
+ 'range' => T.string,
62
+ 'count' => T.integer
63
+ }))
64
+ })
65
+ }).freeze
66
+
67
+ # Validation endpoint with LLM instruction for input validation
68
+ CREATE_USER = RapiTapir.post('/users')
69
+ .json_body(USER_INPUT_SCHEMA)
70
+ .ok(USER_OUTPUT_SCHEMA)
71
+ .error_out(400, VALIDATION_ERROR_SCHEMA)
72
+ .llm_instruction(
73
+ purpose: :validation,
74
+ fields: [:body] # Focus on request body validation
75
+ )
76
+ .summary('Create a new user with validation')
77
+ .description('Creates a new user account with comprehensive input validation and business rule checking')
78
+ .mcp_export
79
+
80
+ # Transformation endpoint for legacy data migration
81
+ MIGRATE_LEGACY_USER = RapiTapir.post('/users/migrate')
82
+ .json_body(LEGACY_USER_INPUT)
83
+ .ok(USER_OUTPUT_SCHEMA)
84
+ .llm_instruction(
85
+ purpose: :transformation,
86
+ fields: :all
87
+ )
88
+ .summary('Migrate legacy user data to new format')
89
+ .description('Transforms legacy user data format to current schema with proper field mapping')
90
+ .mcp_export
91
+
92
+ # Analysis endpoint for user analytics
93
+ USER_ANALYTICS = RapiTapir.get('/users/analytics')
94
+ .query(:start_date, :date)
95
+ .query(:end_date, :date)
96
+ .query(:segment, T.optional(T.string))
97
+ .ok(USER_ANALYTICS_SCHEMA)
98
+ .llm_instruction(
99
+ purpose: :analysis,
100
+ fields: [:json] # Focus on analyzing the response data
101
+ )
102
+ .summary('Get user analytics and insights')
103
+ .description('Provides comprehensive user analytics including demographics and engagement metrics')
104
+ .mcp_export
105
+
106
+ # Documentation endpoint for API reference
107
+ USER_SEARCH = RapiTapir.get('/users/search')
108
+ .query(:q, T.string(min_length: 1))
109
+ .query(:limit, T.optional(T.integer(minimum: 1, maximum: 100)))
110
+ .query(:offset, T.optional(T.integer(minimum: 0)))
111
+ .ok(T.hash({
112
+ 'users' => T.array(USER_OUTPUT_SCHEMA),
113
+ 'total_count' => T.integer,
114
+ 'has_more' => T.boolean
115
+ }))
116
+ .llm_instruction(
117
+ purpose: :documentation,
118
+ fields: :all
119
+ )
120
+ .summary('Search for users')
121
+ .description('Full-text search across user profiles with pagination support')
122
+ .mcp_export
123
+
124
+ # Testing endpoint for comprehensive test generation
125
+ UPDATE_USER = RapiTapir.put('/users/:id')
126
+ .path_param(:id, :integer)
127
+ .json_body(T.hash({
128
+ 'name' => T.optional(T.string(min_length: 2, max_length: 50)),
129
+ 'email' => T.optional(T.email),
130
+ 'preferences' => T.optional(T.hash({
131
+ 'newsletter' => T.boolean,
132
+ 'notifications' => T.boolean
133
+ }))
134
+ }))
135
+ .ok(USER_OUTPUT_SCHEMA)
136
+ .error_out(404, T.hash({'error' => T.string}))
137
+ .error_out(400, VALIDATION_ERROR_SCHEMA)
138
+ .llm_instruction(
139
+ purpose: :testing,
140
+ fields: :all
141
+ )
142
+ .summary('Update user information')
143
+ .description('Updates user profile with partial data and validation')
144
+ .mcp_export
145
+
146
+ # Completion endpoint for smart field suggestions
147
+ USER_PROFILE_COMPLETION = RapiTapir.post('/users/complete')
148
+ .json_body(T.hash({
149
+ 'partial_profile' => T.hash({
150
+ 'name' => T.optional(T.string),
151
+ 'email' => T.optional(T.string),
152
+ 'location' => T.optional(T.string),
153
+ 'interests' => T.optional(T.array(T.string))
154
+ })
155
+ }))
156
+ .ok(T.hash({
157
+ 'suggestions' => T.hash({
158
+ 'name' => T.optional(T.array(T.string)),
159
+ 'email' => T.optional(T.string),
160
+ 'location' => T.optional(T.array(T.string)),
161
+ 'interests' => T.optional(T.array(T.string))
162
+ }),
163
+ 'confidence_scores' => T.hash({
164
+ 'name' => T.optional(T.float),
165
+ 'email' => T.optional(T.float),
166
+ 'location' => T.optional(T.float),
167
+ 'interests' => T.optional(T.float)
168
+ })
169
+ }))
170
+ .llm_instruction(
171
+ purpose: :completion,
172
+ fields: [:body]
173
+ )
174
+ .summary('Get smart profile completion suggestions')
175
+ .description('Provides intelligent suggestions for completing user profile data')
176
+ .mcp_export
177
+ end
178
+
179
+ # Endpoints for CLI
180
+ user_validation_api = [
181
+ UserValidationAPI::CREATE_USER,
182
+ UserValidationAPI::MIGRATE_LEGACY_USER,
183
+ UserValidationAPI::USER_ANALYTICS,
184
+ UserValidationAPI::USER_SEARCH,
185
+ UserValidationAPI::UPDATE_USER,
186
+ UserValidationAPI::USER_PROFILE_COMPLETION
187
+ ]
@@ -1,163 +1,94 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- # This file demonstrates the improved auto-derivation capabilities that work
4
- # well with Ruby's dynamic nature and lack of built-in type declarations
3
+ # This file demonstrates the auto-derivation capabilities of RapiTapir's type
4
+ # system, working well with Ruby's dynamic nature and lack of built-in type
5
+ # declarations.
5
6
 
6
7
  require_relative '../lib/rapitapir/types'
7
8
 
8
- puts "=== RapiTapir Auto-Derivation Examples ==="
9
+ puts '=== RapiTapir Auto-Derivation Examples ==='
9
10
  puts
10
11
 
11
12
  # 1. From Hash (most reliable for Ruby)
12
- puts "1. From Hash (recommended for Ruby)"
13
+ puts '1. From Hash (recommended for Ruby)'
13
14
  hash_data = {
14
- name: "John Doe",
15
+ name: 'John Doe',
15
16
  age: 30,
16
- email: "john@example.com",
17
+ email: 'john@example.com',
17
18
  active: true,
18
19
  score: 95.5,
19
- tags: ["developer", "ruby"],
20
- metadata: { role: "senior", team: "backend" }
20
+ tags: ['developer', 'ruby'],
21
+ metadata: { role: 'senior', team: 'backend' }
21
22
  }
22
23
 
23
24
  schema = RapiTapir::Types.from_hash(hash_data)
24
- puts "Schema from hash:"
25
+ puts 'Schema from hash:'
25
26
  puts schema.field_types.inspect
26
27
  puts
27
28
 
28
29
  # 2. From Hash with filtering
30
+ puts '2. From Hash with filtering'
29
31
  filtered_schema = RapiTapir::Types.from_hash(hash_data, except: [:metadata])
30
32
  puts "Schema with 'except' filtering:"
31
33
  puts filtered_schema.field_types.inspect
32
34
  puts
33
35
 
34
- # 3. From explicit types (recommended for classes)
35
- puts "2. From Class with Explicit Types (recommended)"
36
- class Person
37
- attr_accessor :name, :age, :email, :active
38
- end
39
-
40
- # Method 1: Via types parameter
41
- person_schema = RapiTapir::Types.from_object(Person, types: {
42
- name: :string,
43
- age: :integer,
44
- email: :string,
45
- active: :boolean
46
- })
47
- puts "Person schema with explicit types:"
48
- puts person_schema.field_types.inspect
49
- puts
50
-
51
- # 4. From instance (less reliable but convenient)
52
- puts "3. From Instance (use with well-populated data)"
53
- person = Person.new
54
- person.name = "Jane Smith"
55
- person.age = 28
56
- person.email = "jane@example.com"
57
- person.active = true
58
-
59
- instance_schema = RapiTapir::Types.from_object(person)
60
- puts "Schema from instance:"
61
- puts instance_schema.field_types.inspect
36
+ filtered_only = RapiTapir::Types.from_hash(hash_data, only: [:name, :email])
37
+ puts "Schema with 'only' filtering:"
38
+ puts filtered_only.field_types.inspect
62
39
  puts
63
40
 
64
- # 5. From Struct (good compromise)
65
- puts "4. From Struct (good Ruby pattern)"
66
- Point = Struct.new(:x, :y, :z) do
67
- def distance_from_origin
68
- Math.sqrt(x**2 + y**2 + z**2)
69
- end
70
- end
71
-
72
- sample_point = Point.new(1.0, 2.0, 3.0)
73
- point_schema = RapiTapir::Types.from_object(Point, sample: sample_point)
74
- puts "Point schema from Struct:"
75
- puts point_schema.field_types.inspect
76
- puts
77
-
78
- # 6. DSL approach (most Ruby-like)
79
- puts "5. DSL Approach (Ruby-idiomatic)"
80
- class User
81
- include RapiTapir::Types::AutoDerivation::Annotated
82
-
83
- attr_accessor :username, :email, :age, :admin
84
-
85
- rapitapir_schema do
86
- field :username, :string
87
- field :email, :string
88
- field :age, :integer
89
- field :admin, :boolean
90
- end
91
- end
92
-
93
- user_schema = RapiTapir::Types.from_object(User)
94
- puts "User schema with DSL:"
95
- puts user_schema.field_types.inspect
96
- puts
97
-
98
- # 7. OpenStruct (convenient for prototyping)
99
- puts "6. From OpenStruct"
41
+ # 3. OpenStruct (convenient for prototyping)
42
+ puts '3. From OpenStruct'
100
43
  require 'ostruct'
101
44
 
102
45
  config = OpenStruct.new(
103
- host: "localhost",
46
+ host: 'localhost',
104
47
  port: 3000,
105
48
  ssl: false,
106
49
  timeout: 30.5
107
50
  )
108
51
 
109
52
  config_schema = RapiTapir::Types.from_open_struct(config)
110
- puts "Config schema from OpenStruct:"
53
+ puts 'Config schema from OpenStruct:'
111
54
  puts config_schema.field_types.inspect
112
55
  puts
113
56
 
114
- # 8. JSON Schema (for external APIs)
115
- puts "7. From JSON Schema"
57
+ # 4. JSON Schema (for external APIs)
58
+ puts '4. From JSON Schema'
116
59
  json_schema = {
117
- "type" => "object",
118
- "properties" => {
119
- "id" => { "type" => "integer" },
120
- "name" => { "type" => "string", "maxLength" => 100 },
121
- "email" => { "type" => "string", "format" => "email" },
122
- "created_at" => { "type" => "string", "format" => "date-time" },
123
- "tags" => {
124
- "type" => "array",
125
- "items" => { "type" => "string" }
60
+ 'type' => 'object',
61
+ 'properties' => {
62
+ 'id' => { 'type' => 'integer' },
63
+ 'name' => { 'type' => 'string', 'maxLength' => 100 },
64
+ 'email' => { 'type' => 'string', 'format' => 'email' },
65
+ 'created_at' => { 'type' => 'string', 'format' => 'date-time' },
66
+ 'tags' => {
67
+ 'type' => 'array',
68
+ 'items' => { 'type' => 'string' }
126
69
  }
127
70
  },
128
- "required" => ["id", "name", "email"]
71
+ 'required' => ['id', 'name', 'email']
129
72
  }
130
73
 
131
74
  json_derived_schema = RapiTapir::Types.from_json_schema(json_schema)
132
- puts "Schema from JSON Schema:"
75
+ puts 'Schema from JSON Schema:'
133
76
  puts json_derived_schema.field_types.inspect
134
77
  puts
135
78
 
136
- # 9. Demonstrate the limitations
137
- puts "8. Limitations and Error Handling"
138
-
139
- class EmptyClass
140
- end
141
-
79
+ # 5. Protobuf (when available)
80
+ puts '5. From Protobuf (if a protobuf descriptor is available)'
142
81
  begin
143
- # This should fail gracefully
144
- RapiTapir::Types.from_object(EmptyClass)
145
- rescue ArgumentError => e
146
- puts "Expected error for empty class: #{e.message}"
82
+ require 'google/protobuf' # rubocop:disable Lint/RequireRelativeSelfPath
83
+ puts ' google-protobuf is available — from_protobuf(Descriptor) is supported'
84
+ rescue LoadError
85
+ puts ' google-protobuf not installed — from_protobuf is available once it is'
147
86
  end
148
-
149
- begin
150
- # This should also fail
151
- RapiTapir::Types.from_object(Point) # Struct without sample
152
- rescue ArgumentError => e
153
- puts "Expected error for Struct without sample: #{e.message}"
154
- end
155
-
156
87
  puts
157
- puts "=== Recommendations ==="
158
- puts "1. Use from_hash() for parsed JSON or config data"
159
- puts "2. Use explicit types parameter for Ruby classes"
160
- puts "3. Use DSL annotations for reusable schemas"
161
- puts "4. Use Structs for value objects with samples"
162
- puts "5. Use from_json_schema() for external API integration"
163
- puts "6. Avoid deriving from empty classes or nil values"
88
+
89
+ puts '=== Recommendations ==='
90
+ puts '1. Use from_hash() for parsed JSON or config data'
91
+ puts '2. Use from_open_struct() for prototyping'
92
+ puts '3. Use from_json_schema() for external API integration'
93
+ puts '4. Use from_protobuf() when wrapping protobuf messages'
94
+ puts '5. Avoid deriving from empty hashes or nil values'