rails-openapi-gen 0.0.1

data/lib/rails_openapi_gen/parsers/template_processors/response_template_processor.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsOpenapiGen
+  module Parsers
+    module TemplateProcessors
+      module ResponseTemplateProcessor
+        def extract_template_path(action_node, route)
+          raise NotImplementedError, "#{self.class} must implement #extract_template_path"
+        end
+
+        def find_default_template(route)
+          raise NotImplementedError, "#{self.class} must implement #find_default_template"
+        end
+      end
+    end
+  end
+end

data/lib/rails_openapi_gen/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module RailsOpenapiGen
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks/openapi.rake", __dir__)
+    end
+  end
+end

data/lib/rails_openapi_gen/tasks/openapi.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+namespace :openapi do
+  desc "Generate OpenAPI specification from Rails application"
+  task generate: :environment do
+    require "rails_openapi_gen"
+    RailsOpenapiGen.generate
+  end
+
+  desc "Check for missing @openapi comments and uncommitted changes"
+  task check: :environment do
+    require "rails_openapi_gen"
+    RailsOpenapiGen.check
+  end
+
+  desc "Import OpenAPI specification and add comments to Jbuilder templates"
+  task :import, [:openapi_file] => :environment do |_task, args|
+    require "rails_openapi_gen"
+    
+    openapi_file = args[:openapi_file]
+    
+    if openapi_file.nil? || openapi_file.empty?
+      puts "Usage: bin/rails openapi:import[PATH_TO_OPENAPI_FILE]"
+      puts "Example: bin/rails openapi:import[docs/api/openapi.yaml]"
+      exit 1
+    end
+    
+    RailsOpenapiGen.import(openapi_file)
+  end
+end

data/lib/rails_openapi_gen/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsOpenapiGen
+  VERSION = "0.0.1"
+end

data/lib/rails_openapi_gen.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "rails_openapi_gen/version"
+require "rails_openapi_gen/configuration"
+require "rails_openapi_gen/parsers/comment_parser"
+require "rails_openapi_gen/generators/yaml_generator"
+require "rails_openapi_gen/importer"
+
+# Rails integration is handled by Engine
+
+# Load Rails Engine if Rails is available
+if defined?(Rails::Engine)
+  require "rails_openapi_gen/engine"
+  
+  # Only load parser-dependent components if parser gem is available
+  begin
+    require "parser/current"
+    require "rails_openapi_gen/parsers/routes_parser"
+    require "rails_openapi_gen/parsers/controller_parser"
+    require "rails_openapi_gen/parsers/jbuilder_parser"
+  rescue LoadError
+    # parser gem not available, skip these components
+  end
+end
+
+module RailsOpenapiGen
+  class Error < StandardError; end
+
+  class << self
+    # Generates OpenAPI specification from Rails application
+    # @return [void]
+    def generate
+      Generator.new.run
+    end
+
+    # Checks for missing OpenAPI comments and uncommitted changes
+    # @return [void]
+    def check
+      Checker.new.run
+    end
+
+    # Imports OpenAPI specification and generates @openapi comments in Jbuilder files
+    # @param openapi_file [String, nil] Path to OpenAPI specification file (defaults to openapi/openapi.yaml)
+    # @return [void]
+    def import(openapi_file = nil)
+      Importer.new(openapi_file).run
+    end
+  end
+
+  class Generator
+    # Runs the OpenAPI generation process
+    # @return [void]
+    def run
+      # Load configuration
+      RailsOpenapiGen.configuration.load_from_file
+      
+      routes = Parsers::RoutesParser.new.parse
+      filtered_routes = routes.select { |route| RailsOpenapiGen.configuration.route_included?(route[:path]) }
+      
+      schemas = {}
+
+      filtered_routes.each do |route|
+        controller_info = Parsers::ControllerParser.new(route).parse
+        
+        if controller_info[:jbuilder_path]
+          jbuilder_result = Parsers::JbuilderParser.new(controller_info[:jbuilder_path]).parse
+          schema = build_schema(jbuilder_result[:properties])
+          schemas[route] = {
+            schema: schema,
+            parameters: controller_info[:parameters] || {},
+            operation: jbuilder_result[:operation]
+          }
+        end
+      end
+
+      Generators::YamlGenerator.new(schemas).generate
+      puts "✅ OpenAPI specification generated successfully!"
+    end
+
+    private
+
+    # Builds schema from parsed AST nodes
+    # @param ast [Array<Hash>] Array of parsed AST nodes
+    # @return [Hash] OpenAPI schema definition
+    def build_schema(ast)
+      # Check if this is an array response (json.array!)
+      if ast.any? { |node| node[:is_array_root] }
+        return build_array_schema(ast)
+      end
+      
+      schema = { "type" => "object", "properties" => {}, "required" => [] }
+
+      ast.each do |node|
+        property = node[:property]
+        comment_data = node[:comment_data] || {}
+
+        # Skip array root items as they're handled separately
+        next if node[:is_array_root]
+
+        property_schema = build_property_schema(node)
+        
+        schema["properties"][property] = property_schema
+        # Don't mark conditional properties as required, even if they have required:true
+        if comment_data[:required] == "true" && !node[:is_conditional]
+          schema["required"] << property
+        end
+      end
+
+      schema
+    end
+
+    # Builds array schema from AST nodes containing json.array!
+    # @param ast [Array<Hash>] Array of parsed AST nodes
+    # @return [Hash] OpenAPI array schema definition
+    def build_array_schema(ast)
+      # For json.array! responses, return array schema
+      item_properties = {}
+      required_fields = []
+
+      # Find the array root node to check for array_item_properties
+      array_root_node = ast.find { |node| node[:is_array_root] }
+      
+      if array_root_node && array_root_node[:array_item_properties]
+        # Use properties from the parsed partial
+        array_root_node[:array_item_properties].each do |node|
+          property = node[:property]
+          comment_data = node[:comment_data] || {}
+          
+          property_schema = build_property_schema(node)
+          item_properties[property] = property_schema
+          if comment_data[:required] == "true" && !node[:is_conditional]
+            required_fields << property
+          end
+        end
+      else
+        # Fall back to looking for non-root properties
+        ast.each do |node|
+          next if node[:is_array_root]
+          
+          property = node[:property]
+          comment_data = node[:comment_data] || {}
+          
+          property_schema = build_property_schema(node)
+          item_properties[property] = property_schema
+          if comment_data[:required] == "true" && !node[:is_conditional]
+            required_fields << property
+          end
+        end
+      end
+
+      {
+        "type" => "array",
+        "items" => {
+          "type" => "object",
+          "properties" => item_properties,
+          "required" => required_fields
+        }
+      }
+    end
+
+    # Builds property schema from a single AST node
+    # @param node [Hash] Parsed AST node containing property information
+    # @return [Hash] OpenAPI property schema
+    def build_property_schema(node)
+      comment_data = node[:comment_data] || {}
+      property_schema = {}
+
+      # Handle different property types
+      if node[:is_object] || node[:is_nested]
+        property_schema["type"] = "object"
+        
+        # Build nested properties if they exist
+        if node[:nested_properties] && !node[:nested_properties].empty?
+          nested_schema = build_nested_object_schema(node[:nested_properties])
+          property_schema["properties"] = nested_schema["properties"]
+          property_schema["required"] = nested_schema["required"] if nested_schema["required"] && !nested_schema["required"].empty?
+        end
+      elsif node[:is_array]
+        property_schema["type"] = "array"
+        
+        if node[:array_item_properties] && !node[:array_item_properties].empty?
+          # Build items schema from array iteration block
+          items_schema = build_nested_object_schema(node[:array_item_properties])
+          items_def = {
+            "type" => "object",
+            "properties" => items_schema["properties"]
+          }
+          items_def["required"] = items_schema["required"] if items_schema["required"] && !items_schema["required"].empty?
+          property_schema["items"] = items_def
+        elsif comment_data[:items]
+          # Use specified items type from comment
+          property_schema["items"] = { "type" => comment_data[:items] }
+        else
+          # Default to object items
+          property_schema["items"] = { "type" => "object" }
+        end
+      elsif comment_data[:type] && comment_data[:type] != "TODO: MISSING COMMENT"
+        property_schema["type"] = comment_data[:type]
+        
+        # Handle array types
+        if comment_data[:type] == "array"
+          if comment_data[:items]
+            # Use specified items type
+            property_schema["items"] = { "type" => comment_data[:items] }
+          else
+            # Default to string items if no items type is specified
+            property_schema["items"] = { "type" => "string" }
+          end
+        end
+      else
+        # Only show TODO message if no @openapi comment exists at all
+        property_schema["type"] = "string"
+        if comment_data.nil? || comment_data.empty?
+          property_schema["description"] = "TODO: MISSING COMMENT - Add @openapi comment"
+        end
+      end
+
+      # Add common properties
+      property_schema["description"] = comment_data[:description] if comment_data[:description]
+      property_schema["enum"] = comment_data[:enum] if comment_data[:enum]
+
+      property_schema
+    end
+    
+    # Builds schema for nested object properties
+    # @param nested_properties [Array<Hash>] Array of nested property nodes
+    # @return [Hash] Schema with properties and required fields
+    def build_nested_object_schema(nested_properties)
+      schema = { "properties" => {}, "required" => [] }
+      
+      nested_properties.each do |node|
+        property = node[:property]
+        comment_data = node[:comment_data] || {}
+        
+        property_schema = build_property_schema(node)
+        schema["properties"][property] = property_schema
+        if comment_data[:required] == "true" && !node[:is_conditional]
+          schema["required"] << property
+        end
+      end
+      
+      schema
+    end
+  end
+
+  class Checker
+    # Runs checks for missing comments and uncommitted changes
+    # @return [void]
+    def run
+      system("bin/rails openapi:generate")
+      
+      missing_comments = `grep -r "TODO: MISSING COMMENT" openapi/`.strip
+      unless missing_comments.empty?
+        puts "❌ Missing @openapi comments found!"
+        exit 1
+      end
+
+      diff = `git diff --name-only openapi/`.strip
+      unless diff.empty?
+        puts "❌ OpenAPI spec has uncommitted changes!"
+        exit 1
+      end
+
+      puts "✅ OpenAPI spec is up to date!"
+    end
+  end
+end

data/lib/tasks/openapi_import.rake

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+namespace :openapi do
+  desc "Import OpenAPI specification and add @openapi comments to Jbuilder files"
+  task :import, [:openapi_file] => :environment do |_task, args|
+    openapi_file = args[:openapi_file]
+    
+    # Set debug mode if verbose flag is passed
+    ENV['DEBUG_OPENAPI_IMPORT'] = '1' if ENV['VERBOSE'] == 'true'
+    
+    RailsOpenapiGen.import(openapi_file)
+  end
+  
+  desc "Diagnose import issues by comparing OpenAPI paths with Rails routes"
+  task :diagnose_import, [:openapi_file] => :environment do |_task, args|
+    openapi_file = args[:openapi_file] || File.join(RailsOpenapiGen.configuration.output_directory, 
+                                                     RailsOpenapiGen.configuration.output_filename)
+    
+    unless File.exist?(openapi_file)
+      puts "❌ OpenAPI file not found: #{openapi_file}"
+      exit 1
+    end
+    
+    puts "🔍 Diagnosing OpenAPI import for: #{openapi_file}"
+    puts ""
+    
+    # Load OpenAPI spec
+    openapi_spec = YAML.load_file(openapi_file)
+    openapi_paths = openapi_spec['paths'] || {}
+    
+    # Get Rails routes
+    routes_parser = RailsOpenapiGen::Parsers::RoutesParser.new
+    rails_routes = routes_parser.parse
+    
+    # Group routes by path for easier lookup
+    routes_by_path = rails_routes.group_by { |r| r[:path] }
+    
+    puts "📊 Summary:"
+    puts "   OpenAPI paths: #{openapi_paths.size}"
+    puts "   Rails routes: #{rails_routes.size}"
+    puts ""
+    
+    # Check each OpenAPI path
+    unmatched_paths = []
+    matched_paths = []
+    
+    openapi_paths.each do |path, methods|
+      methods.each do |method, operation|
+        next if method == 'parameters'
+        
+        # Convert OpenAPI path to Rails format
+        rails_path = path.gsub(/\{(\w+)\}/, ':\1')
+        
+        # Try to find matching route
+        matching_routes = rails_routes.select do |route|
+          route[:method] == method.upcase && 
+          route[:path].gsub(/\/$/, '') == rails_path.gsub(/\/$/, '')
+        end
+        
+        if matching_routes.empty?
+          unmatched_paths << { path: path, method: method.upcase, rails_path: rails_path }
+        else
+          matched_paths << { path: path, method: method.upcase, route: matching_routes.first }
+        end
+      end
+    end
+    
+    # Report results
+    if matched_paths.any?
+      puts "✅ Matched paths (#{matched_paths.size}):"
+      matched_paths.each do |match|
+        route = match[:route]
+        controller_path = route[:controller].gsub('/', '::').camelize + "Controller"
+        action = route[:action]
+        puts "   #{match[:method]} #{match[:path]} → #{controller_path}##{action}"
+      end
+      puts ""
+    end
+    
+    if unmatched_paths.any?
+      puts "❌ Unmatched OpenAPI paths (#{unmatched_paths.size}):"
+      unmatched_paths.each do |unmatched|
+        puts "   #{unmatched[:method]} #{unmatched[:path]}"
+        
+        # Suggest similar routes
+        similar_routes = rails_routes.select do |route|
+          route[:method] == unmatched[:method] && 
+          route[:path].include?(unmatched[:rails_path].split('/').reject(&:empty?).first.to_s)
+        end
+        
+        if similar_routes.any?
+          puts "     Did you mean one of these?"
+          similar_routes.take(3).each do |route|
+            puts "       - #{route[:path]}"
+          end
+        end
+      end
+      puts ""
+    end
+    
+    # Check for Jbuilder templates
+    puts "📄 Checking Jbuilder templates:"
+    matched_paths.each do |match|
+      route = match[:route]
+      controller_parser = RailsOpenapiGen::Parsers::ControllerParser.new(route)
+      controller_info = controller_parser.parse
+      
+      if controller_info[:jbuilder_path]
+        if File.exist?(controller_info[:jbuilder_path])
+          puts "   ✅ #{match[:method]} #{match[:path]} → #{controller_info[:jbuilder_path]}"
+        else
+          puts "   ❌ #{match[:method]} #{match[:path]} → #{controller_info[:jbuilder_path]} (file not found)"
+        end
+      else
+        puts "   ⚠️  #{match[:method]} #{match[:path]} → No Jbuilder template found"
+      end
+    end
+    
+    puts ""
+    puts "💡 Tips:"
+    puts "   - Ensure your OpenAPI paths match your Rails routes exactly"
+    puts "   - Use {id} in OpenAPI for :id in Rails routes"
+    puts "   - Create Jbuilder templates for API endpoints that need them"
+    puts "   - Run 'DEBUG_OPENAPI_IMPORT=1 rake openapi:import[#{openapi_file}]' for detailed import logs"
+  end
+end

data/rails-openapi-gen.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "rails-openapi-gen"
+  spec.version = "0.0.1"
+  spec.authors = ["myzkey"]
+  spec.email = ["myzkey.dev@example.com"]
+
+  spec.summary = "Rails comment-driven OpenAPI generator"
+  spec.description = "Generates OpenAPI specs from Rails apps by parsing routes, controllers, and view templates with @openapi comment annotations"
+  spec.homepage = "https://github.com/myzkey/rails-openapi-gen"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.glob("lib/**/*") + Dir.glob("*.md") + Dir.glob("*.gemspec")
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 6.0"
+  spec.add_dependency "parser", "~> 3.2"
+  spec.add_dependency "yaml", "~> 0.2"
+
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: rails-openapi-gen
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- myzkey
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-07-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Generates OpenAPI specs from Rails apps by parsing routes, controllers,
+  and view templates with @openapi comment annotations
+email:
+- myzkey.dev@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CLAUDE.md
+- README.md
+- lib/rails_openapi_gen.rb
+- lib/rails_openapi_gen/configuration.rb
+- lib/rails_openapi_gen/engine.rb
+- lib/rails_openapi_gen/generators/yaml_generator.rb
+- lib/rails_openapi_gen/importer.rb
+- lib/rails_openapi_gen/parsers/comment_parser.rb
+- lib/rails_openapi_gen/parsers/comment_parsers/attribute_parser.rb
+- lib/rails_openapi_gen/parsers/comment_parsers/base_attribute_parser.rb
+- lib/rails_openapi_gen/parsers/comment_parsers/body_parser.rb
+- lib/rails_openapi_gen/parsers/comment_parsers/conditional_parser.rb
+- lib/rails_openapi_gen/parsers/comment_parsers/operation_parser.rb
+- lib/rails_openapi_gen/parsers/comment_parsers/param_parser.rb
+- lib/rails_openapi_gen/parsers/comment_parsers/query_parser.rb
+- lib/rails_openapi_gen/parsers/controller_parser.rb
+- lib/rails_openapi_gen/parsers/jbuilder_parser.rb
+- lib/rails_openapi_gen/parsers/routes_parser.rb
+- lib/rails_openapi_gen/parsers/template_processors/jbuilder_template_processor.rb
+- lib/rails_openapi_gen/parsers/template_processors/response_template_processor.rb
+- lib/rails_openapi_gen/railtie.rb
+- lib/rails_openapi_gen/tasks/openapi.rake
+- lib/rails_openapi_gen/version.rb
+- lib/tasks/openapi_import.rake
+- rails-openapi-gen.gemspec
+homepage: https://github.com/myzkey/rails-openapi-gen
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/myzkey/rails-openapi-gen
+  source_code_uri: https://github.com/myzkey/rails-openapi-gen
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Rails comment-driven OpenAPI generator
+test_files: []