rails-api-docs 0.1.1

data/lib/rails-api-docs/doc/file_builder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RailsApiDocs
+  module Doc
+    # Reads the YAML config and writes the rendered HTML to disk.
+    # Used by `rake rails-api-docs:build`. Extracted as a service so the
+    # rake task body can stay tiny and the build flow is unit-testable.
+    class FileBuilder
+      class MissingConfigError < StandardError; end
+
+      def initialize(config_path:, output_path:)
+        @config_path = config_path
+        @output_path = output_path
+      end
+
+      # Writes the HTML and returns the absolute output path.
+      def call
+        unless File.exist?(@config_path)
+          raise MissingConfigError,
+                "Config file not found at #{@config_path}. " \
+                "Run `rails g rails-api-docs:init` first."
+        end
+
+        config = Config::Loader.load(@config_path)
+        html   = Renderer.new(config).call
+
+        FileUtils.mkdir_p(File.dirname(@output_path))
+        File.write(@output_path, html)
+
+        @output_path
+      end
+    end
+  end
+end

data/lib/rails-api-docs/doc/renderer.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+
+module RailsApiDocs
+  module Doc
+    # Turns the parsed YAML config into the final self-contained HTML
+    # document. Used by both the rake task (writes to public/api-docs.html)
+    # and the dev controller mounted at /rails/api-docs.
+    #
+    # The output is a single HTML string with CSS and JS inlined — no
+    # external assets, no asset pipeline required.
+    class Renderer
+      TEMPLATE_PATH = File.expand_path("../templates/api_docs.html.erb", __dir__)
+
+      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
+
+      def initialize(config)
+        @config = config || {}
+      end
+
+      def call
+        ERB.new(File.read(TEMPLATE_PATH), trim_mode: "-").result(binding)
+      end
+
+      # ===== template helpers — public so ERB binding can reach them =====
+
+      def general
+        @general ||= DEFAULT_GENERAL.merge(@config["general_configurations"] || {})
+      end
+
+      def visible_sections
+        @visible_sections ||= (@config["sections"] || {}).each_with_object({}) do |(key, section), acc|
+          next if section["show"] == false
+
+          endpoints = (section["endpoints"] || []).reject { |e| e["show"] == false }
+          next if endpoints.empty?
+
+          acc[key] = section.merge("endpoints" => endpoints)
+        end
+      end
+
+      def empty?
+        visible_sections.empty?
+      end
+
+      def h(value)
+        ERB::Util.html_escape(value.to_s)
+      end
+
+      def endpoint_id(section_key, endpoint)
+        method = endpoint["method"].to_s.downcase
+        path   = endpoint["path"].to_s.gsub(/[^a-z0-9]+/i, "-").gsub(/^-+|-+$/, "")
+        "#{section_slug(section_key)}--#{method}--#{path}"
+      end
+
+      def section_slug(key)
+        key.to_s.gsub(/[^a-z0-9]+/i, "-")
+      end
+
+      def verb_class(method)
+        "verb-#{method.to_s.downcase}"
+      end
+
+      def verb_label(method)
+        method.to_s.upcase == "DELETE" ? "DEL" : method.to_s.upcase
+      end
+
+      def first_endpoint_id
+        visible_sections.each do |key, section|
+          return endpoint_id(key, section["endpoints"].first)
+        end
+        nil
+      end
+
+      def curl_for(endpoint)
+        CurlRenderer.new(endpoint, base_url: general["base_url"]).call
+      end
+
+      # Returns an array of { status:, description:, example:, headers:, schema: }
+      # always in YAML insertion order. If the user defined `responses:` in
+      # the YAML we honor it verbatim; otherwise we synthesize a single
+      # "200" entry from `response_example` or the inferred body sample.
+      def responses_for(endpoint)
+        if endpoint["responses"].is_a?(Hash) && !endpoint["responses"].empty?
+          endpoint["responses"].map do |status, resp|
+            resp ||= {}
+            {
+              "status"      => status.to_s,
+              "description" => resp["description"].to_s,
+              "example"     => resp["example"].to_s,
+              "headers"     => Array(resp["headers"]),
+              "schema"      => Array(resp["schema"])
+            }
+          end
+        else
+          [{
+            "status"      => "200",
+            "description" => "",
+            "example"     => default_response_example(endpoint),
+            "headers"     => [],
+            "schema"      => []
+          }]
+        end
+      end
+
+      def body_present?(endpoint)
+        endpoint["body"].is_a?(Array) && !endpoint["body"].empty?
+      end
+
+      def headers_present?(endpoint)
+        endpoint["headers"].is_a?(Array) && !endpoint["headers"].empty?
+      end
+
+      def params_present?(endpoint)
+        endpoint["params"].is_a?(Array) && !endpoint["params"].empty?
+      end
+
+      def responses_have_details?(endpoint)
+        responses_for(endpoint).any? do |r|
+          !r["headers"].empty? || !r["schema"].empty? || !r["description"].empty?
+        end
+      end
+
+      # Returns the `data-endpoint-tags='[...]'` attribute (with leading
+      # space) for a sidebar <li>, or an empty string when the endpoint
+      # has no tags. JSON encoding is intentional — robust against tag
+      # values that contain spaces or special characters.
+      def sidebar_tags_attr(endpoint)
+        tags = Array(endpoint["tags"])
+        return "" if tags.empty?
+        %( data-endpoint-tags='#{h(tags.to_json)}')
+      end
+
+      def auth_label(auth)
+        case auth.to_s.downcase
+        when "bearer" then "Bearer auth"
+        when "basic"  then "Basic auth"
+        when "none"   then "No auth"
+        else               auth.to_s
+        end
+      end
+
+      # Renders a single field row with all supported attributes. Used
+      # uniformly by body, params, headers, and response schema — one
+      # source of truth for badge rendering.
+      def render_field(field)
+        parts = []
+        parts << %(<div class="field">)
+        parts << %(<div class="field-row">)
+        parts << %(<span class="field-name">#{h(field["name"])}</span>)
+        parts << %(<span class="field-type">#{h(field["type"])}</span>) if field["type"]
+        parts << %(<span class="field-badge format">#{h(field["format"])}</span>)         if field["format"]
+        parts << %(<span class="field-badge in-path">#{h(field["in"])}</span>)             if field["in"]
+        parts << %(<span class="field-badge readonly">read-only</span>)                    if field["read_only"]
+        parts << %(<span class="field-badge writeonly">write-only</span>)                  if field["write_only"]
+        parts << %(<span class="field-badge nullable">nullable</span>)                     if field["nullable"]
+        parts << %(<span class="field-badge required">Required</span>)                     if field["required"]
+
+        min = field["min"] || field["min_length"]
+        max = field["max"] || field["max_length"]
+        parts << %(<span class="field-meta">min: #{h(min)}</span>)                         if min
+        parts << %(<span class="field-meta">max: #{h(max)}</span>)                         if max
+        parts << %(<span class="field-meta">default: #{h(field["default"])}</span>)        unless field["default"].nil?
+        parts << %(<span class="field-meta mono">pattern: #{h(field["pattern"])}</span>)   if field["pattern"]
+        parts << %(</div>)
+
+        if field["enum"].is_a?(Array) && !field["enum"].empty?
+          values = field["enum"].map { |v| %(<code>#{h(v)}</code>) }.join(" · ")
+          parts << %(<div class="field-enum">one of: #{values}</div>)
+        end
+
+        parts << %(<div class="field-desc">#{h(field["description"])}</div>) if field["description"] && !field["description"].to_s.empty?
+        parts << %(<div class="field-example">Example: <code>#{h(field["example"])}</code></div>) unless field["example"].nil?
+
+        parts << %(</div>)
+        parts.join("\n")
+      end
+
+      # Helper: render an array of fields as joined HTML. Use from the
+      # template like `<%= render_fields(endpoint["body"]) -%>`.
+      def render_fields(fields)
+        Array(fields).map { |f| render_field(f) }.join("\n")
+      end
+
+      def status_class(code)
+        case code.to_s[0]
+        when "2" then "status-2xx"
+        when "3" then "status-3xx"
+        when "4" then "status-4xx"
+        when "5" then "status-5xx"
+        else          ""
+        end
+      end
+
+      private
+
+      def default_response_example(endpoint)
+        return endpoint["response_example"].to_s if endpoint["response_example"]
+
+        if endpoint["body"]
+          sample = endpoint["body"].each_with_object("id" => 1) do |field, acc|
+            # User-provided example wins over the type-derived sample.
+            acc[field["name"]] = field.key?("example") && !field["example"].nil? ?
+                                   field["example"] : sample_value(field["type"])
+          end
+          JSON.pretty_generate(sample)
+        else
+          "{}"
+        end
+      end
+
+      def sample_value(type)
+        RailsApiDocs::SampleValue.for(type)
+      end
+    end
+  end
+end

data/lib/rails-api-docs/doc/responder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RailsApiDocs
+  module Doc
+    # Pure-Ruby responder that decides what to serve at /rails/api-docs.
+    # Sits between the Rails controller and the Renderer so that the
+    # decision logic (file present? render fresh; file missing? show setup
+    # page) can be unit-tested without booting a Rails app.
+    class Responder
+      def initialize(config_path:)
+        @config_path = config_path
+      end
+
+      # Returns [status, html_string].
+      def render
+        if File.exist?(@config_path)
+          html = Doc::Renderer.new(Config::Loader.load(@config_path)).call
+          [200, html]
+        else
+          [404, missing_config_page]
+        end
+      end
+
+      private
+
+      def missing_config_page
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <title>rails-api-docs · setup needed</title>
+            <style>
+              body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width: 640px; margin: 80px auto; padding: 0 24px; color: #1F1F1F; line-height: 1.55; }
+              h1 { color: #CC0000; font-size: 24px; margin-bottom: 16px; letter-spacing: -0.01em; }
+              p { margin: 12px 0; color: #4B5563; }
+              code { background: #F4F4F4; padding: 2px 6px; border-radius: 4px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; color: #1F1F1F; }
+              pre { background: #1B1B1F; color: #E5E5E5; padding: 16px 18px; border-radius: 8px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; margin: 20px 0; overflow-x: auto; }
+              .hint { color: #6B7280; font-size: 13px; margin-top: 28px; }
+            </style>
+          </head>
+          <body>
+            <h1>rails-api-docs is installed — but the config file isn't there yet.</h1>
+            <p>Expected to find <code>#{ERB::Util.html_escape(@config_path)}</code>.</p>
+            <p>Run this in your terminal to generate it from your routes:</p>
+            <pre>$ rails g rails-api-docs:init</pre>
+            <p>Then edit the YAML to add descriptions / examples / body fields, and reload this page.</p>
+            <p class="hint">This page is only mounted in <code>development</code>. The generated <code>public/api-docs.html</code> is what gets served everywhere else — see <code>rake rails-api-docs:build</code>.</p>
+          </body>
+          </html>
+        HTML
+      end
+    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

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