rails-api-docs 0.1.0

data/lib/generators/rails-api-docs/init/init_generator.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails-api-docs"
+
+module RailsApiDocs
+  module Generators
+    # The full implementation lives here. `UpdateGenerator` is a thin alias
+    # subclass that just overrides the namespace — see update_generator.rb.
+    # Both invocations run identical code; the distinction is semantic:
+    #
+    #   rails g rails-api-docs:init    # scaffold the YAML the first time
+    #   rails g rails-api-docs:update  # re-run to absorb new routes
+    #
+    # The generator self-detects whether the YAML already exists and either
+    # creates it fresh (init flow) or appends only new routes (update flow).
+    # Existing entries are never modified — safe to re-run any time.
+    class InitGenerator < ::Rails::Generators::Base
+      # Force the hyphenated namespace so the CLI is `rails g rails-api-docs:init`,
+      # matching the gem name (the module-derived default would be `rails_api_docs:init`).
+      namespace "rails-api-docs:init"
+
+      desc <<~DESC
+        Initialize config/rails-api-docs.yml from your Rails app's routes.
+
+        Scaffolds the full config with every discovered route. To absorb
+        new routes after editing your routes file later, run
+        `rails g rails-api-docs:update` — it appends new routes without
+        touching existing entries.
+      DESC
+
+      # `nil` default lets us distinguish "flag not passed" (fall back to
+      # global config) from explicit `--no-api-only` (override config).
+      class_option :api_only, type: :boolean, default: nil,
+                              desc: "Only include routes whose controller is JSON-returning " \
+                                    "(ActionController::API descendant, or action has `render json:`)"
+
+      class_option :only_controllers, type: :array, default: nil,
+                                      desc: "Whitelist controllers (others are dropped). " \
+                                            "Accepts space-, comma-, or bracket-separated names. " \
+                                            "Bare names match across namespaces (e.g. 'users' matches " \
+                                            "both `users` and `api/v1/users`); paths with '/' are exact. " \
+                                            "Examples:\n" \
+                                            "  --only-controllers users posts\n" \
+                                            "  --only-controllers=users,posts,comments\n" \
+                                            "  --only-controllers=[users,posts,comments]\n" \
+                                            "  --only-controllers api/v1/users  # namespaced exact"
+
+      class_option :verbose_yaml, type: :boolean, default: nil,
+                                  desc: "Emit every possible YAML key per endpoint and field " \
+                                        "(format, enum, default, min/max, pattern, read/write_only, " \
+                                        "nullable, response headers/schema, etc.) with defaults. " \
+                                        "Default (without flag) emits the commonly-edited subset only."
+
+      def create_or_update_config_file
+        routes    = Inspectors::RouteInspector.new(
+                      route_set: RailsApiDocs.configuration.route_source,
+                      config:    scoped_config
+                    ).call
+        routes    = filter_json_only(routes) if api_only?
+
+        inferrer  = Inspectors::BodyInferrer.new(root: destination_root, verbose: verbose_yaml?)
+        generated = Config::Builder.new(routes: routes, body_inferrer: inferrer, verbose: verbose_yaml?).call
+
+        if File.exist?(absolute_path)
+          append_into_existing(generated)
+        else
+          create_fresh(generated)
+        end
+      end
+
+      private
+
+      def api_only?
+        options[:api_only].nil? ? RailsApiDocs.configuration.api_only : options[:api_only]
+      end
+
+      def verbose_yaml?
+        options[:verbose_yaml].nil? ? RailsApiDocs.configuration.verbose_yaml : options[:verbose_yaml]
+      end
+
+      def filter_json_only(routes)
+        detector = Inspectors::JsonRouteDetector.new(root: destination_root)
+        kept     = routes.select { |r| detector.call(controller: r[:controller], action: r[:action]) }
+        skipped  = routes.size - kept.size
+        say_status :filtered, "--api-only kept #{kept.size}/#{routes.size} routes (#{skipped} non-JSON skipped)", :cyan if skipped.positive?
+        kept
+      end
+
+      # Returns a per-run configuration: a dup of the global config with
+      # CLI-supplied options overlaid. Inspectors get this explicit config
+      # so we don't mutate global state.
+      def scoped_config
+        cfg          = RailsApiDocs.configuration.dup
+        only_ctrls   = parse_only_controllers
+        cfg.only_controllers = only_ctrls if only_ctrls
+        cfg
+      end
+
+      # Accepts all four CLI forms:
+      #   --only-controllers users posts            (space — Thor native array)
+      #   --only-controllers=users,posts            (comma)
+      #   --only-controllers=[users,posts,comments] (bracketed)
+      #   --only-controllers=[ users , posts ]      (whitespace inside)
+      # Returns nil if flag wasn't passed, [] if passed but empty after parsing.
+      def parse_only_controllers
+        raw = options[:only_controllers]
+        return nil unless raw
+
+        raw.flat_map { |item| item.gsub(/[\[\]]/, "").split(",") }
+           .map(&:strip)
+           .reject(&:empty?)
+      end
+
+      def relative_path
+        RailsApiDocs.configuration.config_path
+      end
+
+      def absolute_path
+        File.join(destination_root, relative_path)
+      end
+
+      def create_fresh(generated)
+        content = file_header + YAML.dump(generated)
+        create_file relative_path, content
+      end
+
+      def append_into_existing(generated)
+        existing = Config::Loader.load(absolute_path)
+        appender = Config::Appender.new(existing: existing, generated: generated)
+
+        unless appender.changes?
+          say_status :unchanged, relative_path, :yellow
+          return
+        end
+
+        header  = Config::Loader.header(absolute_path)
+        merged  = appender.call
+        content = (header.empty? ? file_header : header) + YAML.dump(merged)
+
+        File.write(absolute_path, content)
+
+        d              = appender.diff
+        new_sections   = d[:new_sections].size
+        new_endpoints  = d[:new_endpoints_by_section].values.sum(&:size)
+        say_status :updated, "#{relative_path} (+#{new_sections} section(s), +#{new_endpoints} endpoint(s))", :green
+      end
+
+      def file_header
+        <<~YAML
+          # config/rails-api-docs.yml
+          # Auto-generated by rails-api-docs.
+          #
+          # You can safely edit this file:
+          #   - Add descriptions, examples, body fields and params.
+          #   - Set `show: false` to hide a route or section from the docs.
+          #   - Tweak `general_configurations` (colors, title, base_url, etc.).
+          #
+          # Re-run `rails g rails-api-docs:update` whenever your routes change —
+          # it only APPENDS new routes; existing entries are never modified.
+          # Delete a section/endpoint from this file to have it regenerated.
+
+        YAML
+      end
+    end
+  end
+end

data/lib/generators/rails-api-docs/update/update_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../init/init_generator"
+
+module RailsApiDocs
+  module Generators
+    # Alias for InitGenerator with a different namespace. Both commands run
+    # the same code; this one reads more naturally for re-runs:
+    #
+    #   rails g rails-api-docs:update              # equivalent to :init
+    #   rails g rails-api-docs:update --api-only   # all flags supported
+    #
+    # The generator's behavior is self-detecting (file exists → append-only
+    # merge; file missing → fresh scaffold), so the practical distinction is
+    # purely the name printed in `rails g --help`.
+    class UpdateGenerator < InitGenerator
+      namespace "rails-api-docs:update"
+
+      desc <<~DESC
+        Update config/rails-api-docs.yml with new routes from your Rails app.
+
+        Append-only: only routes not yet in the YAML are added — existing
+        entries (and your edits) are never modified. Accepts the same flags
+        as `rails g rails-api-docs:init`.
+      DESC
+    end
+  end
+end

data/lib/rails-api-docs/config/appender.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RailsApiDocs
+  module Config
+    # Append-only merge between an existing parsed config and a freshly
+    # generated one.
+    #
+    # Rules:
+    #   - Endpoint identity = "#{method} #{path}".
+    #   - Existing endpoints win on every field (user edits are sacred).
+    #   - New endpoints (not in existing) are appended to their section's
+    #     `endpoints` array in the order returned by RouteInspector.
+    #   - Brand-new sections are appended at the end of `sections`.
+    #   - `general_configurations`: existing keys win; only missing keys
+    #     are filled in from the generated defaults — so a new gem version
+    #     introducing a new option doesn't force a manual edit.
+    class Appender
+      def initialize(existing:, generated:)
+        @existing  = existing  || {}
+        @generated = generated || {}
+      end
+
+      def call
+        {
+          "general_configurations" => merge_general,
+          "sections"               => merge_sections
+        }
+      end
+
+      # { new_sections: [keys...], new_endpoints_by_section: { key => [endpoints...] } }
+      def diff
+        {
+          new_sections: new_section_keys,
+          new_endpoints_by_section: new_endpoints_by_section
+        }
+      end
+
+      def changes?
+        d = diff
+        !d[:new_sections].empty? || !d[:new_endpoints_by_section].empty?
+      end
+
+      private
+
+      def merge_general
+        existing  = @existing["general_configurations"]  || {}
+        generated = @generated["general_configurations"] || {}
+        generated.merge(existing)
+      end
+
+      def merge_sections
+        existing  = @existing["sections"]  || {}
+        generated = @generated["sections"] || {}
+
+        merged = existing.dup
+
+        generated.each do |key, gen_section|
+          merged[key] = merged.key?(key) ? merge_section(merged[key], gen_section) : gen_section
+        end
+
+        merged
+      end
+
+      def merge_section(existing_section, generated_section)
+        existing_endpoints  = existing_section["endpoints"]  || []
+        generated_endpoints = generated_section["endpoints"] || []
+
+        existing_keys = existing_endpoints.map { |e| endpoint_key(e) }
+        new_only      = generated_endpoints.reject { |e| existing_keys.include?(endpoint_key(e)) }
+
+        existing_section.merge("endpoints" => existing_endpoints + new_only)
+      end
+
+      def endpoint_key(endpoint)
+        "#{endpoint['method']} #{endpoint['path']}"
+      end
+
+      def new_section_keys
+        existing_keys  = (@existing["sections"]  || {}).keys
+        generated_keys = (@generated["sections"] || {}).keys
+        generated_keys - existing_keys
+      end
+
+      def new_endpoints_by_section
+        result = {}
+        (@generated["sections"] || {}).each do |section_key, gen_section|
+          existing_section = @existing.dig("sections", section_key)
+          next unless existing_section
+
+          existing_keys = (existing_section["endpoints"] || []).map { |e| endpoint_key(e) }
+          new_endpoints = (gen_section["endpoints"] || []).reject { |e| existing_keys.include?(endpoint_key(e)) }
+          result[section_key] = new_endpoints unless new_endpoints.empty?
+        end
+        result
+      end
+    end
+  end
+end

data/lib/rails-api-docs/config/builder.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "active_support/core_ext/string/inflections"
+
+module RailsApiDocs
+  module Config
+    # Turns the array of route hashes produced by RouteInspector into the
+    # full config structure that gets written to config/rails-api-docs.yml.
+    #
+    # Output shape:
+    #   {
+    #     "general_configurations" => { ... defaults ... },
+    #     "sections" => {
+    #       "<controller_key>" => {
+    #         "name" => "...",
+    #         "description" => "",
+    #         "show" => true,
+    #         "endpoints" => [ { "method" =>, "path" =>, ... }, ... ]
+    #       }
+    #     }
+    #   }
+    class Builder
+      DEFAULT_GENERAL = {
+        "title"           => "API Documentation",
+        "base_url"        => "https://api.example.com",
+        "primary_color"   => "#CC0000",
+        "secondary_color" => "#2E2E2E",
+        "accent_color"    => "#D30001",
+        "font_family"     => "system-ui, -apple-system, sans-serif",
+        "show_curl"       => true,
+        "show_examples"   => true
+      }.freeze
+
+      ACTION_VERB_PHRASE = {
+        "index"   => "List",
+        "show"    => "Show",
+        "new"     => "New",
+        "create"  => "Create",
+        "edit"    => "Edit",
+        "update"  => "Update",
+        "destroy" => "Delete"
+      }.freeze
+
+      def initialize(routes:, general: nil, body_inferrer: nil, verbose: false)
+        @routes        = routes
+        @general       = general || DEFAULT_GENERAL.dup
+        @body_inferrer = body_inferrer
+        @verbose       = verbose
+      end
+
+      def call
+        {
+          "general_configurations" => @general,
+          "sections"               => build_sections
+        }
+      end
+
+      def to_yaml
+        YAML.dump(call)
+      end
+
+      private
+
+      def build_sections
+        @routes.group_by { |r| r[:controller] }.each_with_object({}) do |(controller, routes), acc|
+          acc[controller] = {
+            "name"        => section_name(controller),
+            "description" => "",
+            "show"        => true,
+            "endpoints"   => routes.map { |r| build_endpoint(r) }
+          }
+        end
+      end
+
+      def section_name(controller)
+        controller.split("/").last.to_s.tr("_", " ").split.map(&:capitalize).join(" ")
+      end
+
+      def build_endpoint(route)
+        endpoint = {
+          "method"      => route[:verb],
+          "path"        => route[:path],
+          "name"        => endpoint_name(route),
+          "description" => "",
+          "show"        => true
+        }
+
+        endpoint.merge!(verbose_endpoint_meta) if @verbose
+
+        params = path_params(route)
+        endpoint["params"] = params unless params.empty?
+        endpoint["params"] = [] if @verbose && params.empty?   # discoverability
+
+        body = @body_inferrer&.call(controller: route[:controller], action: route[:action])
+        endpoint["body"] = body if body && !body.empty?
+        endpoint["body"] = [] if @verbose && (body.nil? || body.empty?)
+
+        endpoint["request_example"] = "" if @verbose
+        endpoint["responses"]       = response_stub
+
+        endpoint
+      end
+
+      def response_stub
+        if @verbose
+          { "200" => { "description" => "", "headers" => [], "schema" => [], "example" => "" } }
+        else
+          { "200" => { "description" => "", "example" => "" } }
+        end
+      end
+
+      # Methods (not frozen constants) so each endpoint gets fresh array
+      # values — otherwise YAML.dump emits noisy anchors tying multiple
+      # endpoints together.
+      def verbose_endpoint_meta
+        { "deprecated" => false, "auth" => "", "tags" => [], "headers" => [] }
+      end
+
+      def verbose_field_defaults
+        {
+          "format"      => "",
+          "enum"        => [],
+          "default"     => nil,
+          "min"         => nil,
+          "max"         => nil,
+          "min_length"  => nil,
+          "max_length"  => nil,
+          "pattern"     => "",
+          "read_only"   => false,
+          "write_only"  => false,
+          "nullable"    => false
+        }
+      end
+
+      def path_params(route)
+        Array(route[:path_params]).map do |name|
+          type = path_param_type(name.to_s)
+          base = {
+            "name"        => name.to_s,
+            "type"        => type,
+            "required"    => true,
+            "in"          => "path",
+            "description" => "",
+            "example"     => RailsApiDocs::SampleValue.for(type)
+          }
+          @verbose ? base.merge(verbose_field_defaults) : base
+        end
+      end
+
+      def path_param_type(name)
+        name == "id" || name.end_with?("_id") ? "integer" : "string"
+      end
+
+      def endpoint_name(route)
+        phrase = ACTION_VERB_PHRASE[route[:action]] || humanize(route[:action])
+        noun   = route[:action] == "index" ? pluralize_last_segment(route[:controller])
+                                           : singularize_last_segment(route[:controller])
+        "#{phrase} #{noun.capitalize}"
+      end
+
+      def humanize(action)
+        action.to_s.tr("_", " ").capitalize
+      end
+
+      def singularize_last_segment(controller)
+        controller.split("/").last.to_s.singularize
+      end
+
+      def pluralize_last_segment(controller)
+        controller.split("/").last.to_s.pluralize
+      end
+    end
+  end
+end

data/lib/rails-api-docs/config/loader.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RailsApiDocs
+  module Config
+    module Loader
+      module_function
+
+      def load(path)
+        return {} unless File.exist?(path)
+
+        raw = File.read(path)
+        YAML.safe_load(raw, permitted_classes: [Symbol, Date, Time]) || {}
+      end
+
+      # Returns the leading comment block ("#"-prefixed lines and blank lines
+      # at the top of the file). Used to preserve the auto-generated header
+      # — and any user notes they tacked at the top — across re-runs.
+      def header(path)
+        return "" unless File.exist?(path)
+
+        File.read(path)
+            .lines
+            .take_while { |line| line.start_with?("#") || line.strip.empty? }
+            .join
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RailsApiDocs
+  class Configuration
+    attr_accessor :config_path, :output_path, :mount_path, :mount_in_development,
+                  :ignored_path_prefixes, :ignored_controllers, :ignored_actions,
+                  :only_controllers, :api_only, :verbose_yaml
+    attr_writer :route_source
+
+    def initialize
+      @config_path           = "config/rails-api-docs.yml"
+      @output_path           = "public/api-docs.html"
+      @mount_path            = "/rails/api-docs"
+      @mount_in_development  = true
+      @route_source          = nil
+
+      # User-extensible filters applied by RouteInspector. They stack on top
+      # of the built-in INTERNAL_PREFIXES list — they don't replace it.
+      #
+      # ignored_* are blacklists. only_controllers is a whitelist. Strings
+      # without "/" match by boundary-aware suffix (so "users" matches
+      # `users` and `api/v1/users` but not `super_users`). Strings with "/"
+      # match exactly. Regexps match via `Regexp#match?`.
+      # Blacklist wins when a controller is in both lists.
+      @ignored_path_prefixes = []
+      @ignored_controllers   = []
+      @ignored_actions       = []
+      @only_controllers      = []
+
+      # When true, scaffold only includes routes whose controller is JSON-returning
+      # (inherits from ActionController::API, or has `render json:` in the action body).
+      # Can be set per-run via `rails g rails-api-docs:init --api-only` (or `:update`).
+      @api_only              = false
+
+      # When true, scaffold emits EVERY possible YAML key per endpoint and field
+      # (format, enum, default, min/max, pattern, read/write_only, nullable,
+      # response headers/schema, etc.) with defaults — full discoverability at
+      # the cost of much longer files. Default (false) emits only the commonly-
+      # edited keys: description, example, and the existing inferred fields.
+      # Per-run via `--verbose-yaml`.
+      @verbose_yaml          = false
+    end
+
+    # Default lazy lookup — resolved at call time so Rails.application is set
+    # by the time the generator runs. Tests can inject a custom RouteSet.
+    def route_source
+      @route_source || Rails.application.routes
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module RailsApiDocs
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsApiDocs
+
+    rake_tasks do
+      load File.expand_path("tasks/rails-api-docs.rake", __dir__)
+    end
+
+    generators do
+      require_relative "../generators/rails-api-docs/init/init_generator"
+      require_relative "../generators/rails-api-docs/update/update_generator"
+    end
+
+    initializer "rails_api_docs.mount" do |app|
+      config = RailsApiDocs.configuration
+      if config.mount_in_development && Rails.env.development?
+        app.routes.append do
+          mount RailsApiDocs::Engine, at: config.mount_path, as: :rails_api_docs
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RailsApiDocs
+  module Inspectors
+    # Composes ControllerInspector + SchemaInspector to produce a typed body
+    # field list for write actions (create / update).
+    #
+    # Returned shape per call:
+    #
+    #   [
+    #     { "name" => "email", "type" => "string", "required" => true },
+    #     { "name" => "age",   "type" => "integer", "required" => false }
+    #   ]
+    #
+    # Returns `nil` (not an empty array) when there's nothing useful to add —
+    # the Builder uses that to decide whether to emit a `body:` key at all.
+    class BodyInferrer
+      WRITE_ACTIONS = %w[create update].freeze
+
+      def initialize(root: nil, controller_inspector: nil, schema_inspector: nil, verbose: false)
+        @root                       = root
+        @controller_inspector_class = controller_inspector || ControllerInspector
+        @schema_inspector_class     = schema_inspector     || SchemaInspector
+        @verbose                    = verbose
+        @cache                      = {}
+      end
+
+      def call(controller:, action:)
+        return nil unless WRITE_ACTIONS.include?(action.to_s)
+
+        permitted = controller_permits(controller)
+        return nil if permitted.empty?
+
+        types = column_types(controller)
+
+        permitted.map { |name| build_field(name, types[name]) }
+      end
+
+      private
+
+      def build_field(name, col)
+        type     = col ? col[:type].to_s : "string"
+        required = col ? required?(col) : false
+        base = {
+          "name"        => name,
+          "type"        => type,
+          "required"    => required,
+          "description" => "",
+          "example"     => RailsApiDocs::SampleValue.for(type)
+        }
+        @verbose ? base.merge(verbose_field_defaults) : base
+      end
+
+      # Returned as a fresh hash (and fresh array/value instances inside) so
+      # multiple fields don't share references — otherwise `YAML.dump` emits
+      # noisy anchors (`enum: &1 []` / `enum: *1`) tying them together.
+      def verbose_field_defaults
+        {
+          "format"      => "",
+          "enum"        => [],
+          "default"     => nil,
+          "min"         => nil,
+          "max"         => nil,
+          "min_length"  => nil,
+          "max_length"  => nil,
+          "pattern"     => "",
+          "read_only"   => false,
+          "write_only"  => false,
+          "nullable"    => false
+        }
+      end
+
+      def required?(col)
+        !col[:null] && col[:default].nil?
+      end
+
+      def controller_permits(controller)
+        @cache[[:permits, controller]] ||=
+          @controller_inspector_class.new(controller: controller, root: @root).call
+      end
+
+      def column_types(controller)
+        @cache[[:schema, controller]] ||=
+          @schema_inspector_class.new(controller: controller).call
+      end
+    end
+  end
+end