rails-autodoc 0.1.0

data/lib/rails_autodoc/strong_params_parser.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "parser/current"
+
+module RailsAutodoc
+  class StrongParamsParser
+    include AstTraversal
+
+    ParamsResult = Struct.new(:root_key, :schema, :method_name, keyword_init: true)
+
+    def initialize(source_path:, class_name:)
+      @source_path = source_path
+      @class_name = class_name
+      @buffer, = Parser::CurrentRuby.parse_file(source_path)
+    end
+
+    def param_methods
+      methods = {}
+      each_method_definition(class_node) do |child|
+        method_name = method_name_for(child)
+        next unless method_name.end_with?("_params")
+
+        schema = extract_permit_schema(child)
+        next if schema.nil?
+
+        methods[method_name] = ParamsResult.new(
+          root_key: schema[:root_key],
+          schema: schema[:properties],
+          method_name: method_name
+        )
+      end
+      methods
+    end
+
+    def params_for_action(action_name)
+      action_node = find_action_node(action_name)
+      return nil unless action_node
+
+      called_methods = extract_called_param_methods(action_node)
+      called_methods.each do |method_name|
+        result = param_methods[method_name]
+        return result if result
+      end
+
+      param_methods.values.first
+    end
+
+    def query_params_for_action(action_name)
+      action_node = find_action_node(action_name)
+      return [] unless action_node
+
+      params = []
+      walk_nodes(action_node) do |node|
+        next unless node.type == :send
+
+        method_name = node.children[1]
+        case method_name
+        when :[]
+          param_name = literal_value(node.children[2])
+          if param_name && node.children[0]&.type == :send && node.children[0].children[1] == :params
+            params << param_name.to_s
+          end
+        when :fetch
+          param_name = literal_value(node.children[2])
+          if param_name && node.children[0]&.type == :send && node.children[0].children[1] == :params
+            params << param_name.to_s
+          end
+        end
+      end
+
+      params.uniq.map do |name|
+        { name: name, type: "string", required: false }
+      end
+    end
+
+    private
+
+    def class_node
+      @class_node ||= find_class_node(@buffer, class_name: @class_name)
+    end
+
+    def find_action_node(action_name)
+      each_method_definition(class_node) do |child|
+        next unless child.type == :def
+
+        return child if child.children[0].to_s == action_name.to_s
+      end
+      nil
+    end
+
+    def extract_called_param_methods(action_node)
+      methods = []
+      walk_nodes(action_node) do |node|
+        next unless node.type == :send
+
+        method_name = node.children[1]
+        methods << method_name.to_s if method_name.to_s.end_with?("_params")
+      end
+      methods.uniq
+    end
+
+    def extract_permit_schema(method_node)
+      root_key = nil
+      properties = nil
+
+      walk_nodes(method_node) do |node|
+        next unless node.type == :send
+
+        method_name = node.children[1]
+        if method_name == :require
+          root_key = literal_value(node.children[2])
+        elsif method_name == :permit
+          properties = parse_permit_args(node.children[2..])
+        end
+      end
+
+      return nil unless properties
+
+      { root_key: root_key, properties: properties }
+    end
+
+    def parse_permit_args(args)
+      schema = { type: "object", properties: {}, required: [] }
+
+      args.each do |arg|
+        case arg.type
+        when :sym
+          field = arg.children[0].to_s
+          schema[:properties][field] = { type: "string" }
+          schema[:required] << field
+        when :hash
+          each_hash_pair(arg) do |key_node, value_node|
+            field = literal_value(key_node).to_s
+            schema[:properties][field] = parse_nested_permit_value(value_node)
+            schema[:required] << field
+          end
+        end
+      end
+
+      schema[:required].uniq!
+      schema
+    end
+
+    def each_hash_pair(hash_node, &block)
+      hash_node.children.each do |pair_node|
+        next unless pair_node.type == :pair
+
+        yield pair_node.children[0], pair_node.children[1]
+      end
+    end
+
+    def parse_nested_permit_value(node)
+      case node.type
+      when :array
+        symbols = node.children.compact.select { |child| child.type == :sym }
+        if symbols.any?
+          properties = symbols.to_h do |sym|
+            [sym.children[0].to_s, { type: "string" }]
+          end
+          return {
+            type: "object",
+            properties: properties,
+            required: properties.keys
+          }
+        end
+
+        inner = node.children[0]
+        if inner&.type == :hash
+          parse_permit_args([inner])
+        else
+          { type: "array", items: { type: "string" } }
+        end
+      when :hash
+        parse_permit_args([node])
+      else
+        { type: "string" }
+      end
+    end
+
+    def literal_value(node)
+      case node&.type
+      when :sym then node.children[0]
+      when :str then node.children[0]
+      else node.to_s
+      end
+    end
+  end
+end

data/lib/rails_autodoc/tasks/autodoc.rake

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+namespace :autodoc do
+  desc "Generate OpenAPI specification from Rails routes and controllers"
+  task generate: :environment do
+    spec = RailsAutodoc::Generator.new.generate!
+    path = RailsAutodoc.config.resolved_output_path
+    puts "Generated OpenAPI spec at #{path}"
+    puts "Operations: #{spec.fetch('paths', {}).values.flat_map(&:keys).size}"
+  end
+
+  desc "Verify OpenAPI specification is up to date"
+  task verify: :environment do
+    RailsAutodoc::Generator.new.verify!
+    puts "OpenAPI spec is up to date."
+  end
+
+  desc "List inferred API operations"
+  task routes: :environment do
+    operations = RailsAutodoc::RouteInspector.new.operations
+    operations.each do |operation|
+      puts "#{operation.verb.ljust(7)} #{operation.openapi_path.ljust(40)} #{operation.controller_class.name}##{operation.action}"
+    end
+    puts "\nTotal: #{operations.size} operations"
+  end
+end

data/lib/rails_autodoc/version.rb

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

data/lib/rails_autodoc.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "yaml"
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+require "active_support/dependencies"
+
+require_relative "rails_autodoc/version"
+require_relative "rails_autodoc/ast_traversal"
+require_relative "rails_autodoc/configuration"
+require_relative "rails_autodoc/registry"
+require_relative "rails_autodoc/route_inspector"
+require_relative "rails_autodoc/strong_params_parser"
+require_relative "rails_autodoc/schema_mapper"
+require_relative "rails_autodoc/response_inferencer"
+require_relative "rails_autodoc/serializers/registry"
+require_relative "rails_autodoc/dsl/controller_extensions"
+require_relative "rails_autodoc/openapi_spec_builder"
+require_relative "rails_autodoc/generator"
+
+module RailsAutodoc
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    def reset!
+      @config = Configuration.new
+      @registry = Registry.new
+    end
+  end
+end
+
+require_relative "rails_autodoc/railtie" if defined?(Rails)
+require_relative "rails_autodoc/engine" if defined?(Rails)

data/mkdocs.yml

@@ -0,0 +1,16 @@
+site_name: rails-autodoc
+site_description: Auto-generate OpenAPI documentation from Rails conventions
+theme:
+  name: material
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Configuration: configuration.md
+  - Inference Rules: inference-rules.md
+  - Annotation DSL: annotation-dsl.md
+  - Serializer Support: serializer-support.md
+  - CI Integration: ci-integration.md
+  - Limitations: limitations.md
+  - Migration from rswag: migration-from-rswag.md
+  - Architecture: architecture.md
+  - FAQ: faq.md

data/rails-autodoc.gemspec

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_autodoc/version"
+
+DEFAULT_GEM_FILES = Dir[
+  "{app,config,docs,lib}/**/*",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE.txt",
+  "Rakefile"
+].select { |file| File.file?(File.join(__dir__, file)) }.freeze
+
+Gem::Specification.new do |spec|
+  spec.name = "rails-autodoc"
+  spec.version = RailsAutodoc::VERSION
+  spec.authors = ["Prajjwalkumar Panzade"]
+  spec.email = ["prajjwalbpanzade22@gmail.com"]
+
+  spec.summary = "Auto-generate OpenAPI documentation from Rails routes, strong params, and schemas"
+  spec.description = "Generate and serve OpenAPI 3.0 specs from Rails conventions with optional annotation overrides."
+  spec.homepage = "https://github.com/prajjwalkumarpanzade/rails-autodoc"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    files = begin
+      `git ls-files -z`.split("\x0")
+    rescue StandardError
+      []
+    end
+
+    files = DEFAULT_GEM_FILES if files.empty?
+
+    files.reject do |file|
+      file.start_with?("spec/fixtures/") || file.end_with?(".gem")
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 5.2", "< 9"
+  spec.add_dependency "parser", "~> 3.3"
+  spec.add_dependency "psych", ">= 3.1"
+  spec.add_dependency "railties", ">= 5.2", "< 9"
+
+  spec.add_development_dependency "appraisal"
+  spec.add_development_dependency "combustion", "~> 1.4"
+  spec.add_development_dependency "rails", ">= 5.2", "< 9"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "rubocop", "~> 1.60"
+  spec.add_development_dependency "sqlite3", ">= 1.4", "< 1.7"
+  spec.add_development_dependency "webmock"
+end

data/spec/combustion/config.ru

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require File.expand_path("../config/environment", __dir__)
+run Rails.application

data/spec/dummy/app/assets/config/manifest.js

@@ -0,0 +1 @@
+//= link_tree ../images

data/spec/dummy/app/controllers/api/v1/users_controller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    class UsersController < ActionController::API
+      def index
+        render json: User.all
+      end
+
+      def show
+        user = User.find(params[:id])
+        render json: user
+      end
+
+      def create
+        user = User.new(user_params)
+        if user.save
+          render json: user, status: :created
+        else
+          render json: { errors: user.errors.full_messages }, status: :unprocessable_entity
+        end
+      end
+
+      def update
+        user = User.find(params[:id])
+        if user.update(user_params)
+          render json: user
+        else
+          render json: { errors: user.errors.full_messages }, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        User.find(params[:id]).destroy!
+        head :no_content
+      end
+
+      private
+
+      def user_params
+        params.require(:user).permit(:name, :email, :age, address: %i[street city], tags: [])
+      end
+    end
+  end
+end

data/spec/dummy/app/models/user.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class User < ActiveRecord::Base
+  validates :name, :email, presence: true
+end

data/spec/dummy/config/application.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/all"
+Bundler.require(*Rails.groups)
+require "rails_autodoc"
+
+module Dummy
+  class Application < Rails::Application
+    config.load_defaults Rails::VERSION::STRING.to_f >= 7.0 ? "7.1" : "6.1"
+    config.eager_load = false
+    config.secret_key_base = "0" * 64
+    config.active_record.maintain_test_schema = true
+  end
+end

data/spec/dummy/config/boot.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../../Gemfile", __dir__)
+
+require "bundler/setup"

data/spec/dummy/config/database.yml

@@ -0,0 +1,3 @@
+test:
+  adapter: sqlite3
+  database: ":memory:"

data/spec/dummy/config/environment.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "application"
+
+Rails.application.initialize!

data/spec/dummy/config/environments/test.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Rails.application.configure do
+  config.cache_classes = false
+  config.eager_load = false
+  config.public_file_server.enabled = true
+  config.public_file_server.headers = { "Cache-Control" => "public, max-age=3600" }
+  config.consider_all_requests_local = true
+  config.action_controller.perform_caching = false
+  config.active_support.deprecation = :stderr
+  config.active_record.migration_error = :page_load
+end

data/spec/dummy/config/initializers/rails_autodoc.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+RailsAutodoc.configure do |config|
+  config.title = "Dummy API"
+  config.version = "1.0.0"
+  config.output_path = Rails.root.join("tmp/openapi.yaml")
+  config.exclude_paths = [%r{^/rails/}, %r{^/api-docs}]
+end

data/spec/dummy/config/initializers/sqlite3_boolean.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Rails 5.2 stores sqlite booleans as 't'/'f' by default; use integer 1/0 instead.
+if Gem::Version.new(Rails.version) < Gem::Version.new("6.0")
+  ActiveSupport.on_load(:active_record_sqlite3adapter) do
+    ActiveRecord::ConnectionAdapters::SQLite3Adapter.represent_boolean_as_integer = true
+  end
+end

data/spec/dummy/config/routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  mount RailsAutodoc::Engine => "/api-docs"
+
+  namespace :api do
+    namespace :v1 do
+      resources :users, only: %i[index show create update destroy]
+    end
+  end
+end

data/spec/dummy/db/migrate/001_create_users.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class CreateUsers < ActiveRecord::Migration[6.1]
+  def change
+    create_table :users do |t|
+      t.string :name, null: false
+      t.string :email, null: false
+      t.integer :age
+      t.boolean :active, default: true, null: false
+
+      t.timestamps
+    end
+  end
+end

data/spec/dummy/db/schema.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+ActiveRecord::Schema.define(version: 1) do
+  create_table "users", force: :cascade do |t|
+    t.string "name", null: false
+    t.string "email", null: false
+    t.integer "age"
+    t.boolean "active", default: true, null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+end

data/spec/rails_autodoc/configuration_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::Configuration do
+  subject(:config) { described_class.new }
+
+  it "defines sensible defaults" do
+    expect(config.title).to eq("Rails API")
+    expect(config.version).to eq("1.0.0")
+    expect(config.mount_path).to eq("/api-docs")
+    expect(config.cache_spec_in_dev).to be(true)
+    expect(config.exclude_paths).not_to be_empty
+  end
+
+  it "matches excluded paths against patterns" do
+    expect(config.excluded_path?("/rails/info")).to be(true)
+    expect(config.excluded_path?("/api-docs/spec.json")).to be(true)
+    expect(config.excluded_path?("/api/v1/users")).to be(false)
+  end
+
+  it "resolves output path from config when set" do
+    custom_path = Rails.root.join("tmp/custom-openapi.yaml")
+    config.output_path = custom_path
+
+    expect(config.resolved_output_path).to eq(custom_path)
+  end
+
+  it "falls back to openapi/openapi.yaml under Rails.root" do
+    config.output_path = nil
+
+    expect(config.resolved_output_path).to eq(Rails.root.join("openapi/openapi.yaml"))
+  end
+end

data/spec/rails_autodoc/dsl_integration_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "RailsAutodoc annotation DSL" do
+  let(:generator) { RailsAutodoc::Generator.new }
+
+  before do
+    annotated_controller = Class.new(ActionController::API) do
+      include RailsAutodoc::DSL::ControllerExtensions
+
+      def self.name
+        "Api::V1::UsersController"
+      end
+
+      def create
+        head :created
+      end
+
+      swagger_doc action: :create do
+        summary "Create a user"
+        description "Creates a user with validated params"
+        tag "Users"
+        deprecated true
+        body_param :role, :string, enum: %w[admin user]
+        query_param :include, :string, required: true
+        response 201, ref: "User", description: "Created"
+        response 422, ref: "ValidationError", description: "Invalid"
+        security :bearer_auth
+      end
+    end
+
+    stub_const("Api::V1::UsersController", annotated_controller)
+
+    RailsAutodoc.configure do |config|
+      config.default_security = nil
+    end
+
+    Rails.application.routes.draw do
+      namespace :api do
+        namespace :v1 do
+          resources :users, only: :create
+        end
+      end
+    end
+  end
+
+  it "applies DSL overrides to generated operations" do
+    operation = generator.generate.dig("paths", "/api/v1/users", "post")
+
+    expect(operation["summary"]).to eq("Create a user")
+    expect(operation["description"]).to eq("Creates a user with validated params")
+    expect(operation["deprecated"]).to be(true)
+    expect(operation["tags"]).to include("Users")
+    expect(operation["security"]).to eq([{ "bearer_auth" => [] }])
+
+    role_schema = operation.dig("requestBody", "content", "application/json", "schema", "properties", "role")
+    expect(role_schema).to include("type" => "string", "enum" => %w[admin user])
+
+    include_param = operation["parameters"].find { |entry| entry["name"] == "include" }
+    expect(include_param).to include("in" => "query", "required" => true)
+
+    expect(operation.dig("responses", "201", "description")).to eq("Created")
+    expect(operation.dig("responses", "201", "content", "application/json", "schema",
+                         "$ref")).to eq("#/components/schemas/User")
+    expect(operation.dig("responses", "422", "content", "application/json", "schema",
+                         "$ref")).to eq("#/components/schemas/ValidationError")
+  end
+
+  it "excludes operations when annotated with exclude" do
+    RailsAutodoc.registry.register(Api::V1::UsersController, :create) do
+      exclude true
+    end
+
+    expect(generator.generate.dig("paths", "/api/v1/users", "post")).to be_nil
+  end
+end

data/spec/rails_autodoc/engine_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "RailsAutodoc::Engine", type: :request do
+  before do
+    Rails.application.routes.draw do
+      mount RailsAutodoc::Engine => "/api-docs"
+      get "/health", to: proc { [200, {}, ["ok"]] }
+    end
+  end
+
+  it "serves Swagger UI" do
+    get "/api-docs/"
+    expect(response).to have_http_status(:ok)
+    expect(response.body).to include("swagger-ui")
+  end
+
+  it "serves generated OpenAPI JSON" do
+    get "/api-docs/spec.json"
+    expect(response).to have_http_status(:ok)
+    expect(response.media_type).to include("json")
+    body = JSON.parse(response.body)
+    expect(body["openapi"]).to eq("3.0.3")
+  end
+end