rails-autodoc 0.1.0

data/spec/rails_autodoc/gem_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "RailsAutodoc gem packaging" do
+  it "builds a non-empty gemspec file list" do
+    gemspec = Gem::Specification.load("rails-autodoc.gemspec")
+
+    expect(gemspec.files).not_to be_empty
+    expect(gemspec.files).to include("lib/rails_autodoc.rb")
+    expect(gemspec.files).to include("lib/rails_autodoc/generator.rb")
+    expect(gemspec.files).to include("README.md")
+  end
+
+  it "requires Ruby 2.7 or newer" do
+    gemspec = Gem::Specification.load("rails-autodoc.gemspec")
+
+    expect(gemspec.required_ruby_version).to eq(Gem::Requirement.new(">= 2.7.0"))
+  end
+
+  it "declares runtime dependencies needed for inference" do
+    gemspec = Gem::Specification.load("rails-autodoc.gemspec")
+    names = gemspec.dependencies.map(&:name)
+
+    expect(names).to include("activesupport", "parser", "psych", "railties")
+  end
+end

data/spec/rails_autodoc/generator_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::Generator do
+  subject(:generator) { described_class.new }
+
+  before do
+    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
+  end
+
+  it "generates a valid OpenAPI document" do
+    spec = generator.generate
+    expect(spec["openapi"]).to eq("3.0.3")
+    expect(spec["paths"]).not_to be_empty
+  end
+
+  it "includes user paths" do
+    spec = generator.generate
+    expect(spec["paths"].keys).to include("/api/v1/users", "/api/v1/users/{id}")
+  end
+
+  it "writes spec to configured output path" do
+    generator.generate!
+    expect(RailsAutodoc.config.resolved_output_path).to exist
+  end
+
+  it "verifies unchanged specs" do
+    generator.generate!
+    expect { generator.verify! }.not_to raise_error
+  end
+end

data/spec/rails_autodoc/golden_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Golden OpenAPI fixtures" do
+  before do
+    users_controller = Class.new(ActionController::API) do
+      def self.name
+        "Api::V1::UsersController"
+      end
+
+      def index
+        render json: User.all
+      end
+
+      def create
+        user = User.new(user_params)
+        render json: user, status: :created
+      end
+
+      private
+
+      def user_params
+        params.require(:user).permit(:name, :email, :age, address: %i[street city], tags: [])
+      end
+    end
+
+    stub_const("Api::V1::UsersController", users_controller)
+
+    Rails.application.routes.draw do
+      namespace :api do
+        namespace :v1 do
+          resources :users, only: %i[index create]
+        end
+      end
+    end
+  end
+
+  it "matches expected create request schema fields" do
+    spec = RailsAutodoc::Generator.new.generate
+    post_operation = spec.dig("paths", "/api/v1/users", "post")
+    user_schema = post_operation.dig("requestBody", "content", "application/json", "schema", "properties", "user",
+                                     "properties")
+
+    expect(user_schema.keys).to include("name", "email", "age", "address", "tags")
+    expect(user_schema["age"]["type"]).to eq("integer")
+  end
+
+  it "matches key sections from the golden fixture" do
+    expected = YAML.safe_load(
+      File.read(File.expand_path("../fixtures/expected_specs/users_index_create.yaml", __dir__)),
+      permitted_classes: [Date, Time]
+    )
+    actual = RailsAutodoc::Generator.new.generate
+
+    expect(actual.dig("paths", "/api/v1/users", "get", "responses", "200")).to be_present
+    expect(actual.dig("paths", "/api/v1/users", "post", "requestBody", "required")).to be(true)
+    expect(actual.dig("paths", "/api/v1/users", "post", "responses", "201")).to be_present
+
+    expected_post_schema = expected.dig("paths", "/api/v1/users", "post", "requestBody", "content", "application/json",
+                                        "schema")
+    actual_post_schema = actual.dig("paths", "/api/v1/users", "post", "requestBody", "content", "application/json",
+                                    "schema")
+
+    expect(actual_post_schema).to eq(expected_post_schema)
+  end
+end

data/spec/rails_autodoc/integration_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "RailsAutodoc integration", type: :request do
+  let(:generator) { RailsAutodoc::Generator.new }
+  let(:spec) { generator.generate }
+
+  before do
+    RailsAutodoc.configure do |config|
+      config.title = "Dummy API"
+      config.version = "1.0.0"
+      config.output_path = Rails.root.join("tmp/openapi.yaml")
+    end
+
+    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
+  end
+
+  it "loads the published gem version" do
+    expect(RailsAutodoc::VERSION).to match(/\A\d+\.\d+\.\d+\z/)
+  end
+
+  it "generates a complete OpenAPI document" do
+    expect(spec).to include("openapi", "info", "servers", "tags", "paths", "components")
+    expect(spec["openapi"]).to eq("3.0.3")
+    expect(spec.dig("info", "title")).to eq("Dummy API")
+    expect(spec.dig("info", "version")).to eq("1.0.0")
+    expect(spec["servers"]).not_to be_empty
+    expect(spec["tags"]).not_to be_empty
+  end
+
+  it "documents CRUD user paths" do
+    expect(spec["paths"].keys).to include("/api/v1/users", "/api/v1/users/{id}")
+    expect(spec.dig("paths", "/api/v1/users", "get", "operationId")).to eq("api_v1_users_controller_index")
+    expect(spec.dig("paths", "/api/v1/users", "post", "operationId")).to eq("api_v1_users_controller_create")
+  end
+
+  it "documents path parameters for member routes" do
+    parameters = spec.dig("paths", "/api/v1/users/{id}", "get", "parameters")
+    id_param = parameters.find { |entry| entry["name"] == "id" }
+
+    expect(id_param).to include("in" => "path", "required" => true)
+    expect(id_param.dig("schema", "type")).to eq("string")
+  end
+
+  it "documents nested strong params on create" do
+    user_schema = spec.dig(
+      "paths", "/api/v1/users", "post",
+      "requestBody", "content", "application/json", "schema",
+      "properties", "user", "properties"
+    )
+
+    expect(user_schema.keys).to include("name", "email", "age", "address", "tags")
+    expect(user_schema["age"]["type"]).to eq("integer")
+    expect(user_schema["address"]["type"]).to eq("object")
+    expect(user_schema["tags"]["type"]).to eq("array")
+  end
+
+  it "infers response status codes from controller actions" do
+    expect(spec.dig("paths", "/api/v1/users", "post", "responses").keys).to include("201", "422")
+    expect(spec.dig("paths", "/api/v1/users/{id}", "delete", "responses").keys).to include("204")
+  end
+
+  it "includes User schema in components" do
+    user_component = spec.dig("components", "schemas", "User")
+
+    expect(user_component).to include("type" => "object")
+    expect(user_component).to have_key("properties")
+    expect(user_component["properties"].keys).to include("name", "email", "age", "active")
+  end
+
+  it "does not document excluded mount paths" do
+    expect(spec["paths"].keys).not_to include("/api-docs")
+    expect(spec["paths"].keys).not_to include("/api-docs/spec.json")
+  end
+
+  it "raises when generated output drifts from committed file" do
+    output_path = RailsAutodoc.config.resolved_output_path
+    original = output_path.exist? ? output_path.read : nil
+    generator.generate!
+
+    expect { generator.verify! }.not_to raise_error
+
+    output_path.write("openapi: 3.0.3\ninfo:\n  title: Changed\n")
+
+    expect { generator.verify! }.to raise_error(
+      RailsAutodoc::SpecDriftError,
+      /OpenAPI spec drift detected/
+    )
+  ensure
+    if original
+      output_path.write(original)
+    elsif output_path.exist?
+      output_path.delete
+    end
+  end
+
+  it "serves generated operations over HTTP" do
+    get "/api-docs/spec.json"
+
+    expect(response).to have_http_status(:ok)
+
+    body = JSON.parse(response.body)
+    expect(body.dig("paths", "/api/v1/users", "post", "requestBody")).not_to be_nil
+    expect(body.dig("components", "schemas", "User", "properties", "email", "type")).to eq("string")
+  end
+end

data/spec/rails_autodoc/registry_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::Registry do
+  controller_class = Class.new do
+    def self.name
+      "DocsController"
+    end
+  end
+
+  it "registers annotation overrides" do
+    RailsAutodoc.registry.register(controller_class, :create) do
+      summary "Create resource"
+      tag "Docs"
+      body_param :role, :string, enum: %w[admin user]
+      response 201, ref: "User"
+    end
+
+    annotation = RailsAutodoc.registry.find(controller_class, :create)
+    expect(annotation.summary).to eq("Create resource")
+    expect(annotation.tags).to include("Docs")
+    expect(annotation.body_params.first[:enum]).to eq(%w[admin user])
+    expect(annotation.responses["201"][:ref]).to eq("User")
+  end
+end

data/spec/rails_autodoc/response_inferencer_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::ResponseInferencer do
+  let(:source_path) { File.expand_path("../dummy/app/controllers/api/v1/users_controller.rb", __dir__) }
+
+  subject(:inferencer) do
+    described_class.new(source_path: source_path, class_name: "Api::V1::UsersController")
+  end
+
+  it "infers default GET response" do
+    responses = inferencer.responses_for_action("index", verb: "GET")
+    expect(responses.first.status).to eq("200")
+  end
+
+  it "infers POST created status from render call" do
+    responses = inferencer.responses_for_action("create", verb: "POST")
+    expect(responses.map(&:status)).to include("201")
+  end
+
+  it "infers DELETE no content" do
+    responses = inferencer.responses_for_action("destroy", verb: "DELETE")
+    expect(responses.map(&:status)).to include("204")
+  end
+end

data/spec/rails_autodoc/route_inspector_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::RouteInspector do
+  subject(:operations) { described_class.new.operations }
+
+  before do
+    users_controller = Class.new(ActionController::API) do
+      def self.name
+        "Api::V1::UsersController"
+      end
+
+      def index
+        head :ok
+      end
+
+      def show
+        head :ok
+      end
+
+      def create
+        head :ok
+      end
+    end
+
+    stub_const("Api::V1::UsersController", users_controller)
+
+    Rails.application.routes.draw do
+      namespace :api do
+        namespace :v1 do
+          resources :users, only: %i[index show create]
+        end
+      end
+    end
+  end
+
+  it "discovers REST routes" do
+    expect(operations.map(&:verb)).to include("GET", "POST")
+  end
+
+  it "extracts path parameters" do
+    show_operation = operations.find { |op| op.action == "show" }
+    expect(show_operation.path_params).to include("id")
+  end
+
+  it "normalizes OpenAPI path templates" do
+    show_operation = operations.find { |op| op.action == "show" }
+    expect(show_operation.openapi_path).to eq("/api/v1/users/{id}")
+  end
+
+  it "assigns controller tags" do
+    operation = operations.find { |op| op.action == "index" }
+    expect(operation.tags).to include("Users")
+  end
+end

data/spec/rails_autodoc/schema_mapper_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::SchemaMapper do
+  let(:schema_path) { Rails.root.join("db/schema.rb") }
+
+  subject(:mapper) { described_class.new(schema_path: schema_path) }
+
+  it "loads tables from schema.rb" do
+    expect(mapper.all_model_schemas).to have_key("User")
+  end
+
+  it "maps string columns" do
+    schema = mapper.model_schema("User")
+    expect(schema[:properties]["name"][:type]).to eq("string")
+  end
+
+  it "maps integer columns" do
+    schema = mapper.model_schema("User")
+    expect(schema[:properties]["age"][:type]).to eq("integer")
+  end
+
+  it "maps boolean columns" do
+    schema = mapper.model_schema("User")
+    expect(schema[:properties]["active"][:type]).to eq("boolean")
+  end
+
+  it "applies model types to param schemas" do
+    param_schema = {
+      type: "object",
+      properties: {
+        "name" => { type: "string" },
+        "age" => { type: "string" }
+      },
+      required: []
+    }
+
+    mapper.apply_types!(param_schema, model_name: "User")
+    expect(param_schema[:properties]["age"][:type]).to eq("integer")
+  end
+end

data/spec/rails_autodoc/serializers/registry_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::Serializers::Registry do
+  let(:registry) { described_class.new }
+
+  describe "Blueprinter adapter" do
+    let(:serializer_class) do
+      Class.new do
+        def self.name
+          "UserBlueprint"
+        end
+
+        def self.fields
+          { id: {}, email: {}, name: {} }
+        end
+      end
+    end
+
+    before do
+      stub_const("Blueprinter", Module.new)
+      stub_const("Blueprinter::Base", Class.new)
+    end
+
+    it "builds schema from serializer fields" do
+      adapter = RailsAutodoc::Serializers::Blueprinter.new
+      allow(adapter).to receive(:detect?).and_return(true)
+      schema = adapter.schema_for(serializer_class)
+      expect(schema[:properties].keys).to include("id", "email", "name")
+    end
+  end
+end

data/spec/rails_autodoc/strong_params_parser_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe RailsAutodoc::StrongParamsParser do
+  let(:source_path) { File.expand_path("../fixtures/controllers/sample_controller.rb", __dir__) }
+
+  subject(:parser) do
+    described_class.new(source_path: source_path, class_name: "SampleController")
+  end
+
+  it "extracts param methods" do
+    methods = parser.param_methods
+    expect(methods).to have_key("sample_params")
+  end
+
+  it "parses required root key" do
+    result = parser.param_methods["sample_params"]
+    expect(result.root_key).to eq(:sample)
+  end
+
+  it "parses scalar permitted fields" do
+    properties = parser.param_methods["sample_params"].schema[:properties]
+    expect(properties).to include("name", "email")
+  end
+
+  it "parses nested hash fields" do
+    properties = parser.param_methods["sample_params"].schema[:properties]
+    expect(properties["address"][:type]).to eq("object")
+  end
+
+  it "parses array fields" do
+    properties = parser.param_methods["sample_params"].schema[:properties]
+    expect(properties["tags"][:type]).to eq("array")
+  end
+
+  it "maps params to actions" do
+    result = parser.params_for_action("create")
+    expect(result.method_name).to eq("sample_params")
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails"
+require "rails_autodoc"
+require "combustion"
+
+Combustion.path = "spec/dummy"
+Combustion.initialize! :all
+
+[Rails.root.join("app/models"), Rails.root.join("app/controllers")].each do |load_path|
+  Dir[load_path.join("**", "*.rb")].sort.each { |path| require path }
+end
+
+require "rspec/rails"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.example_status_persistence_file_path = "spec/examples.txt"
+  config.disable_monkey_patching!
+  config.order = :random
+  Kernel.srand config.seed
+
+  config.before(:each) do
+    RailsAutodoc.registry.clear!
+    load Rails.root.join("config/initializers/rails_autodoc.rb")
+    clear_spec_controller_cache
+  end
+end
+
+def clear_spec_controller_cache
+  return unless defined?(RailsAutodoc::SpecController)
+
+  RailsAutodoc::SpecController.cached_spec = nil
+end