rails-autodoc 0.1.0

data/lib/generators/rails_autodoc/templates/autodoc-verify.yml

@@ -0,0 +1,19 @@
+name: Autodoc Verify
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+      - name: Verify OpenAPI spec
+        run: bundle exec rake autodoc:verify

data/lib/generators/rails_autodoc/templates/initializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+RailsAutodoc.configure do |config|
+  config.title = "<%= Rails.application.class.module_parent_name %> API"
+  config.version = "1.0.0"
+  config.description = "Auto-generated API documentation"
+  config.mount_path = "/api-docs"
+  config.output_path = Rails.root.join("openapi/openapi.yaml")
+  config.exclude_paths = [%r{^/rails/}, %r{^/api-docs}]
+  config.cache_spec_in_dev = true
+
+  # config.security_schemes = {
+  #   "bearer_auth" => {
+  #     "type" => "http",
+  #     "scheme" => "bearer",
+  #     "bearerFormat" => "JWT"
+  #   }
+  # }
+  # config.default_security = :bearer_auth
+end

data/lib/rails_autodoc/ast_traversal.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  module AstTraversal
+    private
+
+    def walk_nodes(node, &block)
+      yield node
+
+      node.children.compact.each do |child|
+        walk_nodes(child, &block) if child.is_a?(Parser::AST::Node)
+      end
+    end
+
+    def each_method_definition(class_node, &block)
+      return unless class_node
+
+      walk_nodes(class_node) do |node|
+        yield node if method_definition?(node)
+      end
+    end
+
+    def method_definition?(node)
+      %i[def defs].include?(node.type)
+    end
+
+    def method_name_for(node)
+      case node.type
+      when :def then node.children[0].to_s
+      when :defs then node.children[1].to_s
+      end
+    end
+
+    def find_class_node(node, class_name: nil)
+      return nil unless node
+
+      if node.type == :class && (class_name.nil? || class_name_matches?(node, class_name))
+        node
+      else
+        node.children.compact.each do |child|
+          next unless child.is_a?(Parser::AST::Node)
+
+          found = find_class_node(child, class_name: class_name)
+          return found if found
+        end
+        nil
+      end
+    end
+
+    def class_name_matches?(node, class_name)
+      const_node = node.children[0]
+      return false unless const_node
+
+      full_name = const_path(const_node)
+      simple_name = class_name.split("::").last
+
+      full_name == class_name ||
+        full_name == simple_name ||
+        class_name.end_with?("::#{full_name}") ||
+        full_name.end_with?("::#{simple_name}")
+    end
+
+    def const_path(node)
+      case node.type
+      when :const
+        parent = node.children[0]
+        name = node.children[1].to_s
+        parent ? "#{const_path(parent)}::#{name}" : name
+      else
+        ""
+      end
+    end
+  end
+end

data/lib/rails_autodoc/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  class Configuration
+    attr_accessor :title,
+                  :version,
+                  :description,
+                  :mount_path,
+                  :output_path,
+                  :exclude_paths,
+                  :include_engines,
+                  :default_security,
+                  :cache_spec_in_dev,
+                  :servers,
+                  :security_schemes
+
+    def initialize
+      @title = "Rails API"
+      @version = "1.0.0"
+      @description = "Auto-generated API documentation"
+      @mount_path = "/api-docs"
+      @output_path = nil
+      @exclude_paths = [%r{^/rails/}, %r{^/api-docs}]
+      @include_engines = []
+      @default_security = nil
+      @cache_spec_in_dev = true
+      @servers = []
+      @security_schemes = {}
+    end
+
+    def excluded_path?(path)
+      exclude_paths.any? { |pattern| pattern.match?(path) }
+    end
+
+    def resolved_output_path
+      return output_path if output_path
+
+      if defined?(Rails) && Rails.respond_to?(:root)
+        Rails.root.join("openapi/openapi.yaml")
+      else
+        Pathname.new("openapi/openapi.yaml")
+      end
+    end
+  end
+end

data/lib/rails_autodoc/dsl/controller_extensions.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  module DSL
+    module ControllerExtensions
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def swagger_doc(action:, &block)
+          RailsAutodoc.registry.register(self, action, &block)
+        end
+      end
+
+      class AnnotationBuilder
+        def initialize(annotation)
+          @annotation = annotation
+        end
+
+        def summary(text)
+          @annotation.summary = text
+        end
+
+        def description(text)
+          @annotation.description = text
+        end
+
+        def tag(*tags)
+          @annotation.tags.concat(tags.map(&:to_s))
+        end
+
+        def deprecated(value = true)
+          @annotation.deprecated = value
+        end
+
+        def exclude(value = true)
+          @annotation.exclude = value
+        end
+
+        def body_param(name, type, options = {})
+          @annotation.body_params << { name: name.to_s, type: type.to_s }.merge(options)
+        end
+
+        def query_param(name, type, options = {})
+          @annotation.query_params << {
+            name: name.to_s,
+            type: type.to_s,
+            required: options.fetch(:required, false)
+          }.merge(options)
+        end
+
+        def response(status, options = {})
+          @annotation.responses[status.to_s] = options
+        end
+
+        def security(scheme)
+          @annotation.security = scheme
+        end
+
+        def request_body(schema)
+          @annotation.request_body_schema = schema
+        end
+      end
+    end
+  end
+end

data/lib/rails_autodoc/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "../rails_autodoc" unless defined?(RailsAutodoc) && RailsAutodoc.respond_to?(:configure)
+
+module RailsAutodoc
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsAutodoc
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+  end
+end

data/lib/rails_autodoc/generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module RailsAutodoc
+  class Generator
+    def initialize(config: RailsAutodoc.config)
+      @config = config
+    end
+
+    def generate
+      operations = RouteInspector.new(config: @config).operations
+      OpenapiSpecBuilder.new(operations: operations, config: @config).build
+    end
+
+    def generate!
+      spec = generate
+      write_spec(spec)
+      spec
+    end
+
+    def write_spec(spec)
+      output_path = @config.resolved_output_path
+      output_path.dirname.mkpath
+      output_path.write(YAML.dump(spec))
+      spec
+    end
+
+    def to_json(*_args)
+      JSON.pretty_generate(generate)
+    end
+
+    def verify!
+      output_path = @config.resolved_output_path
+      current = output_path.exist? ? YAML.safe_load(output_path.read, permitted_classes: [Date, Time]) : {}
+      fresh = generate
+
+      unless normalize_spec(current) == normalize_spec(fresh)
+        raise SpecDriftError, "OpenAPI spec drift detected at #{output_path}. Run `rake autodoc:generate`."
+      end
+
+      true
+    end
+
+    private
+
+    def normalize_spec(spec)
+      JSON.pretty_generate(spec)
+    end
+  end
+
+  class SpecDriftError < StandardError; end
+end

data/lib/rails_autodoc/openapi_spec_builder.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  class OpenapiSpecBuilder
+    def initialize(
+      operations:,
+      config: RailsAutodoc.config,
+      registry: RailsAutodoc.registry,
+      schema_mapper: SchemaMapper.new
+    )
+      @operations = operations
+      @config = config
+      @registry = registry
+      @schema_mapper = schema_mapper
+    end
+
+    def build
+      {
+        "openapi" => "3.0.3",
+        "info" => info_block,
+        "servers" => servers_block,
+        "tags" => tags_block,
+        "paths" => paths_block,
+        "components" => components_block
+      }.compact
+    end
+
+    private
+
+    def info_block
+      {
+        "title" => @config.title,
+        "version" => @config.version,
+        "description" => @config.description
+      }.compact
+    end
+
+    def servers_block
+      return @config.servers if @config.servers.any?
+
+      if defined?(Rails) && Rails.application.routes.default_url_options[:host]
+        host = Rails.application.routes.default_url_options[:host]
+        [{ "url" => "https://#{host}" }]
+      else
+        [{ "url" => "http://localhost:3000" }]
+      end
+    end
+
+    def tags_block
+      @operations.flat_map(&:tags).uniq.sort.map { |tag| { "name" => tag } }
+    end
+
+    def paths_block
+      paths = {}
+
+      @operations.each do |operation|
+        annotation = @registry.find(operation.controller_class, operation.action)
+        next if annotation&.exclude
+
+        path_key = operation.openapi_path
+        paths[path_key] ||= {}
+        paths[path_key][operation.verb.downcase] = build_operation(operation, annotation)
+      end
+
+      paths
+    end
+
+    def build_operation(operation, annotation)
+      model_name = @schema_mapper.infer_model_from_controller(operation.controller_class)
+      request_body = build_request_body(operation, annotation, model_name)
+      responses = build_responses(operation, annotation, model_name)
+
+      operation_hash = {
+        "operationId" => annotation&.operation_id || operation.operation_id,
+        "tags" => merged_tags(operation, annotation),
+        "summary" => annotation&.summary || "#{operation.verb} #{operation.openapi_path}",
+        "description" => annotation&.description,
+        "deprecated" => annotation&.deprecated || false,
+        "parameters" => build_parameters(operation, annotation),
+        "responses" => responses
+      }
+
+      operation_hash["requestBody"] = request_body if request_body
+      operation_hash["security"] = build_security(annotation) if annotation&.security || @config.default_security
+      operation_hash.compact
+    end
+
+    def merged_tags(operation, annotation)
+      tags = operation.tags.dup
+      tags.concat(annotation.tags) if annotation&.tags&.any?
+      tags.uniq
+    end
+
+    def build_parameters(operation, annotation)
+      params = operation.path_params.map do |name|
+        {
+          "name" => name,
+          "in" => "path",
+          "required" => true,
+          "schema" => { "type" => "string" }
+        }
+      end
+
+      annotation&.query_params&.each do |query_param|
+        params << {
+          "name" => query_param[:name],
+          "in" => "query",
+          "required" => query_param.fetch(:required, false),
+          "schema" => query_schema(query_param)
+        }
+      end
+
+      inferred_query_params(operation).each do |query_param|
+        next if params.any? { |entry| entry["name"] == query_param[:name] }
+
+        params << {
+          "name" => query_param[:name],
+          "in" => "query",
+          "required" => query_param.fetch(:required, false),
+          "schema" => query_schema(query_param)
+        }
+      end
+
+      params
+    end
+
+    def inferred_query_params(operation)
+      source_path = controller_source_path(operation.controller_class)
+      return [] unless source_path&.exist?
+
+      StrongParamsParser.new(
+        source_path: source_path,
+        class_name: operation.controller_class.name
+      ).query_params_for_action(operation.action)
+    rescue StandardError
+      []
+    end
+
+    def query_schema(query_param)
+      schema = { "type" => query_param[:type] || "string" }
+      schema["enum"] = query_param[:enum] if query_param[:enum]
+      schema
+    end
+
+    def build_request_body(operation, annotation, model_name)
+      if annotation&.request_body_schema
+        return {
+          "required" => true,
+          "content" => {
+            "application/json" => {
+              "schema" => annotation.request_body_schema
+            }
+          }
+        }
+      end
+
+      schema = infer_request_schema(operation, model_name)
+
+      schema = { type: "object", properties: {}, required: [] } if schema.nil? && annotation&.body_params&.any?
+
+      return nil unless schema
+
+      if annotation&.body_params&.any?
+        schema[:properties] ||= {}
+        schema[:required] ||= []
+
+        annotation.body_params.each do |param|
+          schema[:properties][param[:name]] = {
+            "type" => param[:type]
+          }.tap do |entry|
+            entry["enum"] = param[:enum] if param[:enum]
+          end
+          schema[:required] << param[:name] unless schema[:required].include?(param[:name])
+        end
+      end
+
+      {
+        "required" => true,
+        "content" => {
+          "application/json" => {
+            "schema" => deep_stringify(schema)
+          }
+        }
+      }
+    end
+
+    def infer_request_schema(operation, model_name)
+      source_path = controller_source_path(operation.controller_class)
+      return nil unless source_path&.exist?
+
+      parser = StrongParamsParser.new(
+        source_path: source_path,
+        class_name: operation.controller_class.name
+      )
+      params_result = parser.params_for_action(operation.action)
+      return nil unless params_result
+
+      schema = params_result.schema.dup
+      @schema_mapper.apply_types!(schema, model_name: model_name)
+
+      if params_result.root_key
+        {
+          type: "object",
+          properties: {
+            params_result.root_key.to_s => deep_stringify(schema)
+          },
+          required: [params_result.root_key.to_s]
+        }
+      else
+        schema
+      end
+    rescue StandardError
+      nil
+    end
+
+    def build_responses(operation, annotation, model_name)
+      if annotation&.responses&.any?
+        return annotation.responses.transform_keys(&:to_s).transform_values do |response|
+          build_response_entry(response)
+        end
+      end
+
+      source_path = controller_source_path(operation.controller_class)
+      hints = if source_path&.exist?
+                ResponseInferencer.new(
+                  source_path: source_path,
+                  class_name: operation.controller_class.name
+                ).responses_for_action(operation.action, verb: operation.verb)
+              else
+                []
+              end
+
+      if hints.empty?
+        hints = [ResponseInferencer::ResponseHint.new(status: "200", schema: { type: "object" },
+                                                      description: "Successful response")]
+      end
+
+      hints.each_with_object({}) do |hint, hash|
+        entry = { "description" => hint.description || "Response" }
+        if hint.schema
+          entry["content"] = {
+            "application/json" => {
+              "schema" => deep_stringify(hint.schema)
+            }
+          }
+        elsif hint.schema_ref
+          entry["content"] = {
+            "application/json" => {
+              "schema" => { "$ref" => "#/components/schemas/#{hint.schema_ref}" }
+            }
+          }
+        elsif model_name && hint.status != "204"
+          entry["content"] = {
+            "application/json" => {
+              "schema" => { "$ref" => "#/components/schemas/#{model_name}" }
+            }
+          }
+        end
+        hash[hint.status] = entry
+      end
+    end
+
+    def build_response_entry(response)
+      entry = { "description" => response[:description] || "Response" }
+      if response[:ref]
+        entry["content"] = {
+          "application/json" => {
+            "schema" => { "$ref" => "#/components/schemas/#{response[:ref]}" }
+          }
+        }
+      elsif response[:schema]
+        entry["content"] = {
+          "application/json" => {
+            "schema" => deep_stringify(response[:schema])
+          }
+        }
+      end
+      entry
+    end
+
+    def build_security(annotation)
+      scheme = annotation&.security || @config.default_security
+      [{ scheme.to_s => [] }]
+    end
+
+    def components_block
+      schemas = @schema_mapper.all_model_schemas
+      components = {}
+      components["schemas"] = schemas.transform_values { |schema| deep_stringify(schema) } if schemas.any?
+      components["securitySchemes"] = @config.security_schemes if @config.security_schemes.any?
+      components.presence
+    end
+
+    def controller_source_path(controller_class)
+      conventional_controller_path(controller_class) || existing_source_location_path(controller_class)
+    end
+
+    def existing_source_location_path(controller_class)
+      path = source_location_path(controller_class)
+      path if path&.exist?
+    end
+
+    def source_location_path(controller_class)
+      return nil unless controller_class.respond_to?(:instance_method)
+
+      Pathname.new(controller_class.instance_method(:initialize).source_location.first)
+    rescue StandardError
+      nil
+    end
+
+    def conventional_controller_path(controller_class)
+      return nil unless defined?(Rails) && Rails.respond_to?(:root)
+
+      relative = "#{controller_class.name.underscore}.rb"
+      path = Rails.root.join("app/controllers", relative)
+      path.exist? ? path : nil
+    end
+
+    def deep_stringify(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, val), result|
+          result[key.to_s] = deep_stringify(val)
+        end
+      when Array
+        value.map { |item| deep_stringify(item) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+  end
+end

data/lib/rails_autodoc/railtie.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RailsAutodoc
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "rails_autodoc/tasks/autodoc.rake"
+    end
+
+    initializer "rails_autodoc.configure" do
+      if Rails.root.join("config/initializers/rails_autodoc.rb").exist?
+        require Rails.root.join("config/initializers/rails_autodoc.rb")
+      end
+    end
+
+    initializer "rails_autodoc.dsl" do
+      ActiveSupport.on_load(:action_controller) do
+        include RailsAutodoc::DSL::ControllerExtensions
+      end
+    end
+
+    config.to_prepare do
+      RailsAutodoc.registry.clear! if Rails.env.development?
+    end
+  end
+end