rails-api-docs 0.1.0

data/lib/rails-api-docs/inspectors/controller_inspector.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module RailsApiDocs
+  module Inspectors
+    # Walks a controller file via Prism and returns the list of attribute
+    # names declared in any `params.require(:X).permit(...)` (or
+    # `params.permit(...)`) call inside the file.
+    #
+    # This is a deliberately coarse pass — we don't try to map a permit
+    # call back to a specific action. In typical Rails controllers strong
+    # params live in a single shared `*_params` method used by both create
+    # and update, so the flat list of permitted attributes is enough for
+    # documentation purposes.
+    #
+    # Limitations (Phase 5):
+    #   - Nested permits (`permit(items: [:name])`) — only top-level scalar
+    #     keys are extracted; the nested array is ignored.
+    #   - Method-call args inside permit (e.g. `permit(*PERMITTED)`) — not
+    #     resolved; only literal symbols/strings are picked up.
+    class ControllerInspector
+      def initialize(controller:, root: nil)
+        @controller = controller
+        @root       = root || (defined?(Rails) && Rails.root ? Rails.root.to_s : ".")
+      end
+
+      def call
+        return [] unless File.exist?(file_path)
+
+        result  = Prism.parse_file(file_path)
+        visitor = PermitVisitor.new
+        visitor.visit(result.value)
+
+        visitor.permitted.uniq.map(&:to_s)
+      end
+
+      def file_path
+        File.join(@root, "app/controllers", "#{@controller}_controller.rb")
+      end
+
+      class PermitVisitor < ::Prism::Visitor
+        attr_reader :permitted
+
+        def initialize
+          @permitted = []
+          super
+        end
+
+        def visit_call_node(node)
+          collect_permitted(node) if node.name == :permit
+          super
+        end
+
+        private
+
+        def collect_permitted(node)
+          args = node.arguments&.arguments || []
+          args.each do |arg|
+            case arg
+            when ::Prism::SymbolNode
+              @permitted << arg.value
+            when ::Prism::StringNode
+              @permitted << arg.unescaped
+            when ::Prism::KeywordHashNode, ::Prism::HashNode
+              # Nested permits — pick up the top-level keys only.
+              arg.elements.each do |element|
+                next unless element.respond_to?(:key)
+                key = element.key
+                @permitted << key.value if key.is_a?(::Prism::SymbolNode)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails-api-docs/inspectors/json_route_detector.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "prism"
+require "set"
+require "active_support/core_ext/string/inflections"
+
+module RailsApiDocs
+  module Inspectors
+    # Decides whether an endpoint should be considered "JSON-returning" for
+    # the `--api-only` filter on the install generator.
+    #
+    # Decision logic for `call(controller:, action:)`:
+    #   1. If the controller's inheritance chain reaches `ActionController::API`
+    #      (directly, or transitively via ApplicationController / a custom
+    #      base controller) → true for every action.
+    #   2. Else if the action body contains a `render json: …` call (kwarg
+    #      form or hash-rocket form, including inside `respond_to` blocks)
+    #      → true.
+    #   3. Else → false.
+    #
+    # `:unknown` classifications (controller file missing, unresolvable
+    # parent constant) are strict — they DO NOT count as :api. Per-action
+    # render-json detection still runs if the file exists but inheritance
+    # is unresolvable.
+    #
+    # Each controller file is parsed at most once per detector instance —
+    # the same Prism AST feeds both visitors, and the result hash is cached
+    # so the inheritance chain ApplicationController → ActionController::API
+    # is walked once even when 50 controllers inherit from it.
+    #
+    # Known limitations:
+    #   - `render json:` inside a helper method called from the action is
+    #     not detected (we don't follow method calls).
+    #   - `render template: "x", formats: :json` doesn't have a `json:`
+    #     key in the call, so it's missed.
+    #   - Includes (`include SomeRenderingModule`) are not traversed.
+    class JsonRouteDetector
+      def initialize(root: nil)
+        @root  = root || (defined?(Rails) && Rails.root ? Rails.root.to_s : ".")
+        @cache = {}
+      end
+
+      def call(controller:, action:)
+        profile = profile_for(controller)
+        return true  if profile[:type] == :api
+        profile[:json_actions].include?(action.to_s)
+      end
+
+      # Exposed for testing / debugging.
+      def profile_for(controller)
+        @cache[controller] ||= analyze(controller)
+      end
+
+      private
+
+      def analyze(controller)
+        file = controller_path(controller)
+        return blank_profile unless File.exist?(file)
+
+        ast = ::Prism.parse_file(file).value
+
+        sc_visitor = SuperclassVisitor.new
+        sc_visitor.visit(ast)
+
+        ja_visitor = JsonActionVisitor.new
+        ja_visitor.visit(ast)
+
+        {
+          type:         classify(sc_visitor.superclass),
+          json_actions: ja_visitor.actions
+        }
+      end
+
+      def classify(parent_name)
+        return :unknown unless parent_name
+
+        case parent_name
+        when "ActionController::API"  then :api
+        when "ActionController::Base" then :html
+        else
+          parent_controller = parent_name.underscore.sub(/_controller\z/, "")
+          # Guard against pathological cycles (e.g. file that references
+          # itself somehow). The cache hit on second visit makes the loop
+          # short-circuit because we'd recurse into ourselves and read
+          # back the same in-progress entry — but to be safe, mark visited.
+          return :unknown if @cache.key?(parent_controller)
+
+          @cache[parent_controller] = blank_profile   # placeholder to break cycles
+          @cache[parent_controller] = analyze(parent_controller)
+          @cache[parent_controller][:type]
+        end
+      end
+
+      def blank_profile
+        { type: :unknown, json_actions: [] }
+      end
+
+      def controller_path(controller)
+        File.join(@root, "app/controllers", "#{controller}_controller.rb")
+      end
+
+      # ============================================================
+      # Visitors
+      # ============================================================
+
+      # Captures the superclass name from the FIRST class definition in
+      # the file. Handles both simple constants (`ApplicationController`)
+      # and qualified ones (`ActionController::API`, `Api::V1::BaseController`).
+      class SuperclassVisitor < ::Prism::Visitor
+        attr_reader :superclass
+
+        def visit_class_node(node)
+          @superclass ||= constant_name(node.superclass)
+          super
+        end
+
+        private
+
+        def constant_name(node)
+          case node
+          when nil
+            nil
+          when ::Prism::ConstantReadNode
+            node.name.to_s
+          when ::Prism::ConstantPathNode
+            parts = []
+            walk = node
+            while walk.is_a?(::Prism::ConstantPathNode)
+              parts.unshift(walk.name.to_s)
+              walk = walk.parent
+            end
+            parts.unshift(walk.name.to_s) if walk.is_a?(::Prism::ConstantReadNode)
+            parts.join("::")
+          end
+        end
+      end
+
+      # Walks every method definition and records the names of methods that
+      # contain a `render` call with a `json:` keyword. Nested calls inside
+      # `respond_to do |format| format.json { render json: … } end` are
+      # caught because `super` recurses into child nodes.
+      class JsonActionVisitor < ::Prism::Visitor
+        def initialize
+          @actions        = Set.new
+          @current_method = nil
+          super
+        end
+
+        def actions
+          @actions.to_a
+        end
+
+        def visit_def_node(node)
+          prev = @current_method
+          @current_method = node.name.to_s
+          super
+          @current_method = prev
+        end
+
+        def visit_call_node(node)
+          if @current_method && node.name == :render && renders_json?(node)
+            @actions.add(@current_method)
+          end
+          super
+        end
+
+        private
+
+        def renders_json?(call_node)
+          args = call_node.arguments&.arguments || []
+          args.any? { |arg| has_json_key?(arg) }
+        end
+
+        def has_json_key?(node)
+          case node
+          when ::Prism::KeywordHashNode, ::Prism::HashNode
+            node.elements.any? do |elem|
+              next false unless elem.respond_to?(:key)
+              key = elem.key
+              key.is_a?(::Prism::SymbolNode) && key.value.to_s == "json"
+            end
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails-api-docs/inspectors/route_inspector.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module RailsApiDocs
+  module Inspectors
+    # Walks a Rails route set and produces a normalized array of hashes
+    # describing each user-facing route:
+    #
+    #   { verb:, path:, controller:, action:, name:, path_params: }
+    #
+    # Internal Rails routes (mailers, conductor, active_storage, etc.) are
+    # skipped. Routes without a resolvable controller/action are skipped.
+    class RouteInspector
+      INTERNAL_PREFIXES = %w[
+        /rails/info
+        /rails/conductor
+        /rails/mailers
+        /rails/active_storage
+        /rails/action_mailbox
+        /action_cable
+        /assets
+      ].freeze
+
+      def initialize(route_set: nil, config: nil)
+        @route_set = route_set || (defined?(Rails) && Rails.application&.routes)
+        @config    = config    || (defined?(RailsApiDocs) ? RailsApiDocs.configuration : nil)
+        raise ArgumentError, "no route set available" unless @route_set
+      end
+
+      def call
+        @route_set.routes.flat_map { |route| extract(route) }.compact
+      end
+
+      private
+
+      def extract(route)
+        controller = route.defaults[:controller]
+        action     = route.defaults[:action]
+        return [] unless controller && action
+        return [] if ignored_controller?(controller.to_s)
+        return [] if only_controllers_active? && !only_controllers_match?(controller.to_s)
+        return [] if ignored_action?(action.to_s)
+
+        path = normalize_path(route.path.spec.to_s)
+        return [] if internal?(path) || user_ignored?(path)
+
+        verbs = verbs_for(route)
+        return [] if verbs.empty?
+
+        verbs.map do |verb|
+          {
+            verb: verb,
+            path: path,
+            controller: controller.to_s,
+            action: action.to_s,
+            name: route.name,
+            path_params: extract_path_params(path)
+          }
+        end
+      end
+
+      def ignored_controller?(controller)
+        Array(@config&.ignored_controllers).any? { |pattern| controller_matches?(pattern, controller) }
+      end
+
+      def only_controllers_active?
+        Array(@config&.only_controllers).any?
+      end
+
+      def only_controllers_match?(controller)
+        Array(@config&.only_controllers).any? { |pattern| controller_matches?(pattern, controller) }
+      end
+
+      # Shared rule for matching a controller path against a user-supplied
+      # pattern. Used by both the blacklist (ignored_controllers) and the
+      # whitelist (only_controllers) so the two are symmetric.
+      #
+      # Rules:
+      #   - Regexp pattern → standard regex match.
+      #   - String containing "/" → exact path match. So "api/v1/users"
+      #     matches only that exact controller, not the bare "users".
+      #   - String without "/" → boundary-aware suffix match. So "users"
+      #     matches both `users` and `api/v1/users`, but NOT `super_users`
+      #     (the boundary requires a "/" before the pattern, or equality).
+      def controller_matches?(pattern, controller)
+        return pattern.match?(controller) if pattern.is_a?(Regexp)
+
+        s = pattern.to_s
+        if s.include?("/")
+          controller == s
+        else
+          controller == s || controller.end_with?("/#{s}")
+        end
+      end
+
+      def ignored_action?(action)
+        Array(@config&.ignored_actions).include?(action)
+      end
+
+      def user_ignored?(path)
+        Array(@config&.ignored_path_prefixes).any? { |prefix| path.start_with?(prefix) }
+      end
+
+      def normalize_path(raw)
+        raw.sub(/\(\.:format\)\z/, "").sub(/\/\z/, "").then { |p| p.empty? ? "/" : p }
+      end
+
+      def internal?(path)
+        INTERNAL_PREFIXES.any? { |prefix| path.start_with?(prefix) }
+      end
+
+      # `route.verb` is a String in modern Rails ("GET", "POST", ...).
+      # When a route accepts multiple verbs (via `match via: [:get, :post]`)
+      # it can return a regex-source string like "GET|POST" — we split it.
+      def verbs_for(route)
+        raw = route.verb.to_s
+        return [] if raw.empty?
+
+        raw.split("|").map { |v| v.upcase.strip }.reject(&:empty?)
+      end
+
+      def extract_path_params(path)
+        path.scan(/:(\w+)/).flatten
+      end
+    end
+  end
+end

data/lib/rails-api-docs/inspectors/schema_inspector.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RailsApiDocs
+  module Inspectors
+    # Looks up the ActiveRecord model corresponding to a controller and
+    # returns its columns metadata:
+    #
+    #   { "name" => { type: :string, null: false, default: nil }, ... }
+    #
+    # If the model can't be resolved or ActiveRecord isn't loaded, returns
+    # an empty hash — schema inference is always best-effort.
+    class SchemaInspector
+      DEFAULT_RESOLVER = lambda do |controller|
+        last       = controller.split("/").last.to_s
+        model_name = last.singularize.camelize
+        Object.const_get(model_name) if Object.const_defined?(model_name)
+      end
+
+      def initialize(controller:, model_resolver: nil)
+        @controller     = controller
+        @model_resolver = model_resolver || DEFAULT_RESOLVER
+      end
+
+      def call
+        model = @model_resolver.call(@controller)
+        return {} unless model && model.respond_to?(:columns_hash)
+
+        model.columns_hash.each_with_object({}) do |(name, col), acc|
+          acc[name.to_s] = { type: col.type, null: col.null, default: col.default }
+        end
+      rescue StandardError
+        {}
+      end
+    end
+  end
+end

data/lib/rails-api-docs/sample_value.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsApiDocs
+  # Single source of truth for type-derived placeholder values. Used by:
+  #   - BodyInferrer  → seeds `example:` for inferred body fields
+  #   - Builder       → seeds `example:` for inferred path params
+  #   - CurlRenderer  → fills body fields in `--data` when no example is set
+  #   - Renderer      → synthesizes a default response example from body schema
+  #
+  # The mapping is intentionally narrow — for niche types it returns nil
+  # rather than guessing, which JSON-encodes to `null` and signals to the
+  # user "we don't know, fill this in".
+  module SampleValue
+    module_function
+
+    def for(type)
+      case type.to_s
+      when "string", "text"    then "example"
+      when "integer", "bigint" then 1
+      when "float", "decimal"  then 1.0
+      when "boolean"           then true
+      when "date"              then "2026-01-01"
+      when "datetime", "time"  then "2026-01-01T00:00:00Z"
+      else                          nil
+      end
+    end
+  end
+end

data/lib/rails-api-docs/tasks/rails-api-docs.rake

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+namespace :"rails-api-docs" do
+  desc "Generate the API docs HTML at public/api-docs.html from config/rails-api-docs.yml.\n" \
+       "Override paths with CONFIG= and OUTPUT= env vars if needed."
+  task build: :environment do
+    config_relative = ENV["CONFIG"] || RailsApiDocs.configuration.config_path
+    output_relative = ENV["OUTPUT"] || RailsApiDocs.configuration.output_path
+
+    config_path = Rails.root.join(config_relative).to_s
+    output_path = Rails.root.join(output_relative).to_s
+
+    begin
+      written = RailsApiDocs::Doc::FileBuilder.new(
+        config_path: config_path,
+        output_path: output_path
+      ).call
+
+      puts "[rails-api-docs] wrote #{written} (#{File.size(written)} bytes)"
+    rescue RailsApiDocs::Doc::FileBuilder::MissingConfigError => e
+      warn "[rails-api-docs] #{e.message}"
+      exit 1
+    end
+  end
+end