reqcord 0.1.0 → 0.1.1

data/examples/test-app/generate.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Stands in for `bin/rails reqcord:generate`, which this single file example
+# has no `bin/rails` to run.
+require_relative "app"
+
+dataset = Reqcord::Generator.call(
+  resources: ENV.fetch("RESOURCE", "").split(",").map(&:strip).reject(&:empty?),
+  version: ENV["VERSION"]
+)
+
+puts
+puts "Endpoints: #{dataset.endpoints.size} (#{dataset.documented_endpoints.size} covered by tests)"
+puts "Output: #{Reqcord.configuration.output_directory}"

data/examples/test-app/reqcord.yml

@@ -0,0 +1,28 @@
+version: 1
+
+test:
+  framework: minitest
+  # A directory is enough. There is no bin/rails here, so Reqcord runs every
+  # *_test.rb beneath it itself; in a Rails app it runs `bin/rails test <path>`.
+  paths:
+    - test/integration
+
+routes:
+  prefix: /api
+
+output:
+  directory: docs/api
+
+exporters:
+  - curl
+  - markdown
+  - postman
+
+variables:
+  base_url: http://localhost:3000
+
+sanitize:
+  headers:
+    Authorization: "Bearer {{token}}"
+  body:
+    password: "{{password}}"

data/examples/test-app/test/integration/customers_test.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Ordinary Rails integration tests. Nothing here mentions Reqcord: the
+# documentation is generated from the requests these tests already make.
+require_relative "../../app"
+require "minitest/autorun"
+
+class CustomersTest < ActionDispatch::IntegrationTest
+  def auth
+    { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" }
+  end
+
+  test "lists customers" do
+    get "/api/v1/customers", params: { per_page: 1 }, headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "shows customer" do
+    get "/api/v1/customers/1", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "returns not found for an unknown customer" do
+    get "/api/v1/customers/999", headers: auth, as: :json
+
+    assert_response :not_found
+  end
+
+  test "creates an active customer" do
+    post "/api/v1/customers",
+         params: { customer: { name: "Ada Lovelace", email: "ada@example.com", status: "active" } },
+         headers: auth,
+         as: :json
+
+    assert_response :created
+  end
+
+  test "creates a passive customer" do
+    post "/api/v1/customers",
+         params: { customer: { name: "Grace Hopper", email: "grace@example.com", status: "passive" } },
+         headers: auth,
+         as: :json
+
+    assert_response :created
+  end
+
+  test "rejects an unknown status" do
+    post "/api/v1/customers",
+         params: { customer: { name: "Ada Lovelace", email: "ada@example.com", status: "inactive" } },
+         headers: auth,
+         as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "rejects a customer without an email" do
+    post "/api/v1/customers",
+         params: { customer: { name: "Ada Lovelace", email: "", status: "active" } },
+         headers: auth,
+         as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "requires authentication" do
+    get "/api/v1/customers", as: :json
+
+    assert_response :unauthorized
+  end
+end

data/examples/test-app/test/integration/tasks_test.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Ordinary Rails integration tests. Nothing here mentions Reqcord: the
+# documentation is generated from the requests these tests already make.
+require_relative "../../app"
+require "minitest/autorun"
+
+class TasksTest < ActionDispatch::IntegrationTest
+  test "lists tasks" do
+    get "/api/v1/tasks", as: :json
+
+    assert_response :ok
+  end
+
+  test "lists open tasks" do
+    get "/api/v1/tasks", params: { status: "open" }, as: :json
+
+    assert_response :ok
+  end
+
+  test "lists done tasks" do
+    get "/api/v1/tasks", params: { status: "done" }, as: :json
+
+    assert_response :ok
+  end
+
+  test "shows a task" do
+    get "/api/v1/tasks/1", as: :json
+
+    assert_response :ok
+  end
+
+  test "returns not found for an unknown task" do
+    get "/api/v1/tasks/999", as: :json
+
+    assert_response :not_found
+  end
+
+  test "creates a high priority task" do
+    post "/api/v1/tasks", params: { task: { title: "Review the release", priority: "high" } }, as: :json
+
+    assert_response :created
+  end
+
+  test "creates a low priority task" do
+    post "/api/v1/tasks", params: { task: { title: "Water the plants", priority: "low" } }, as: :json
+
+    assert_response :created
+  end
+
+  test "rejects a task without a title" do
+    post "/api/v1/tasks", params: { task: { title: "", priority: "high" } }, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "rejects an unknown priority" do
+    post "/api/v1/tasks", params: { task: { title: "Anything", priority: "urgent" } }, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "updates a task" do
+    patch "/api/v1/tasks/1", params: { task: { title: "Write better docs" } }, as: :json
+
+    assert_response :ok
+  end
+
+  test "completes a task" do
+    post "/api/v1/tasks/1/complete", as: :json
+
+    assert_response :ok
+  end
+
+  test "deletes a task" do
+    delete "/api/v1/tasks/3", as: :json
+
+    assert_response :no_content
+  end
+end

data/examples/test-app/test/integration/users_test.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Ordinary Rails integration tests. Nothing here mentions Reqcord: the
+# documentation is generated from the requests these tests already make.
+require_relative "../../app"
+require "minitest/autorun"
+
+class UsersTest < ActionDispatch::IntegrationTest
+  def auth
+    { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" }
+  end
+
+  test "lists users" do
+    get "/api/v1/users", params: { per_page: 1 }, headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "shows user" do
+    get "/api/v1/users/1", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "returns not found for an unknown user" do
+    get "/api/v1/users/999", headers: auth, as: :json
+
+    assert_response :not_found
+  end
+
+  test "creates an active user" do
+    post "/api/v1/users",
+         params: { user: { name: "Ada Lovelace", email: "ada@example.com", status: "active" } },
+         headers: auth,
+         as: :json
+
+    assert_response :created
+  end
+
+  test "creates a inactive user" do
+    post "/api/v1/users",
+         params: { user: { name: "Grace Hopper", email: "grace@example.com", status: "inactive" } },
+         headers: auth,
+         as: :json
+
+    assert_response :created
+  end
+
+  test "rejects an unknown status" do
+    post "/api/v1/users",
+         params: { user: { name: "Ada Lovelace", email: "ada@example.com", status: "passive" } },
+         headers: auth,
+         as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "rejects a user without an email" do
+    post "/api/v1/users",
+         params: { user: { name: "Ada Lovelace", email: "", status: "active" } },
+         headers: auth,
+         as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "requires authentication" do
+    get "/api/v1/users", as: :json
+
+    assert_response :unauthorized
+  end
+end

data/lib/reqcord/capture/collector.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    # Appends one JSON line per exchange. The lock keeps parallel test workers
+    # from interleaving partial lines in the same file.
+    class Collector
+      class << self
+        def write(exchange)
+          return unless Capture.enabled?
+
+          path = Capture.capture_file
+
+          FileUtils.mkdir_p(File.dirname(path))
+
+          File.open(path, "a") do |file|
+            file.flock(File::LOCK_EX)
+
+            file.puts(
+              JSON.generate(exchange)
+            )
+
+            file.flush
+          ensure
+            file.flock(File::LOCK_UN)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/reqcord/capture/integration_patch.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    # Captures exactly what the integration test passed to Rails. Reqcord does
+    # not reconstruct the payload from controller params: the test call is the
+    # source of truth for generated cURL examples.
+    module IntegrationPatch
+      RAILS_DEFAULT_ACCEPT =
+        "text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5"
+
+      def process(method, path, **kwargs)
+        raw_params = kwargs[:params]
+        raw_headers = kwargs[:headers]
+        request_format = kwargs[:as]
+
+        result = super
+
+        if Reqcord::Capture.enabled?
+          Reqcord::Capture::Collector.write(
+            reqcord_exchange(
+              method: method,
+              path: path,
+              params: raw_params,
+              input_headers: raw_headers,
+              request_format: request_format
+            )
+          )
+        end
+
+        result
+      end
+
+      private
+
+      def reqcord_exchange(method:, path:, params:, input_headers:, request_format:)
+        verb = method.to_s.upcase
+        query_params, body = reqcord_split_params(verb, path, params)
+
+        {
+          request: {
+            method: verb,
+            path: reqcord_request_path(path),
+            path_params: reqcord_path_parameters,
+            query_params: query_params,
+            headers: reqcord_request_headers(input_headers, body, request_format),
+            body: body,
+            content_type: reqcord_content_type(body, request_format)
+          },
+          response: {
+            status: response&.status,
+            headers: reqcord_response_headers,
+            body: reqcord_response_body,
+            content_type: response&.media_type
+          },
+          source: TestContext.current
+        }
+      end
+
+      # Keep the concrete test URL (/customers/42), not the route pattern
+      # (/customers/:id). A generated cURL command must be runnable as-is.
+      def reqcord_request_path(path)
+        URI.parse(path.to_s).path
+      rescue URI::InvalidURIError
+        path.to_s.split("?").first
+      end
+
+      def reqcord_path_parameters
+        return {} unless request
+
+        request.path_parameters
+               .except(:controller, :action, :format)
+               .transform_keys(&:to_s)
+      end
+
+      # Rails integration tests use params as query parameters for GET/HEAD and
+      # as the request payload for mutating verbs. Read the original test input
+      # instead of trying to reverse-engineer it from ActionDispatch afterwards.
+      def reqcord_split_params(verb, path, params)
+        explicit_query = reqcord_query_from_path(path)
+        normalized = reqcord_normalize_value(params)
+
+        if %w[GET HEAD].include?(verb)
+          query = explicit_query
+          query = reqcord_deep_merge(query, normalized) if normalized.is_a?(Hash)
+          [query, nil]
+        else
+          [explicit_query, reqcord_meaningful?(normalized) ? normalized : nil]
+        end
+      end
+
+      def reqcord_query_from_path(path)
+        uri = URI.parse(path.to_s)
+        return {} if uri.query.nil? || uri.query.empty?
+
+        Rack::Utils.parse_nested_query(uri.query)
+      rescue URI::InvalidURIError
+        {}
+      end
+
+      def reqcord_request_headers(input_headers, body, request_format)
+        result = {}
+
+        (input_headers || {}).each do |key, value|
+          result[reqcord_header_name(key)] = reqcord_normalize_value(value)
+        end
+
+        result.delete("X-Http-Method-Override")
+
+        if body
+          content_type = reqcord_content_type(body, request_format)
+          result["Content-Type"] ||= content_type if content_type
+        end
+
+        if request
+          accept = request.headers["Accept"]
+          result["Accept"] ||= accept if accept.present? && accept != RAILS_DEFAULT_ACCEPT
+        end
+
+        result
+      end
+
+      def reqcord_content_type(body, request_format)
+        return nil unless body
+
+        return "application/json" if request_format.to_s == "json"
+
+        request&.content_type
+      end
+
+      def reqcord_header_name(key)
+        name = key.to_s
+
+        return name if name.include?("-")
+
+        name.delete_prefix("HTTP_")
+            .split("_")
+            .map { |part| part.empty? ? part : part.capitalize }
+            .join("-")
+      end
+
+      def reqcord_response_headers
+        return {} unless response
+
+        response.headers.to_h
+      end
+
+      def reqcord_response_body
+        return nil unless response
+
+        body = response.body
+        return nil if body.nil? || body.empty?
+
+        if response.media_type == "application/json"
+          JSON.parse(body)
+        else
+          body
+        end
+      rescue JSON::ParserError
+        body
+      end
+
+      def reqcord_normalize_value(value)
+        case value
+        when nil, true, false, Numeric, String
+          value
+        when Symbol
+          value.to_s
+        when Hash
+          value.each_with_object({}) do |(key, nested), result|
+            result[key.to_s] = reqcord_normalize_value(nested)
+          end
+        when Array
+          value.map { |item| reqcord_normalize_value(item) }
+        else
+          if value.respond_to?(:to_unsafe_h)
+            reqcord_normalize_value(value.to_unsafe_h)
+          elsif value.respond_to?(:to_h)
+            reqcord_normalize_value(value.to_h)
+          elsif value.respond_to?(:as_json)
+            reqcord_normalize_value(value.as_json)
+          else
+            value.to_s
+          end
+        end
+      end
+
+      def reqcord_deep_merge(left, right)
+        left.merge(right) do |_key, old_value, new_value|
+          if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+            reqcord_deep_merge(old_value, new_value)
+          else
+            new_value
+          end
+        end
+      end
+
+      def reqcord_meaningful?(value)
+        case value
+        when nil then false
+        when Hash then value.any? { |_key, nested| reqcord_meaningful?(nested) }
+        when Array then value.any? { |item| reqcord_meaningful?(item) }
+        when String then !value.empty?
+        else true
+        end
+      end
+    end
+  end
+end

data/lib/reqcord/capture/minitest_context.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    module MinitestContext
+      def before_setup
+        file, line = reqcord_source_location
+
+        TestContext.current = {
+          test: name,
+          suite: self.class.name,
+          file: file,
+          line: line
+        }
+
+        super
+      end
+
+      def after_teardown
+        super
+      ensure
+        TestContext.clear
+      end
+
+      private
+
+      def reqcord_source_location
+        method(name).source_location
+      rescue NameError
+        [nil, nil]
+      end
+    end
+  end
+end

data/lib/reqcord/capture/rspec_context.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    # The RSpec counterpart of MinitestContext: names captured examples after
+    # the request spec that produced them.
+    module RSpecContext
+      class << self
+        def install!(rspec = ::RSpec)
+          return false if @installed
+
+          rspec.configure do |config|
+            config.before(:each) do |example|
+              TestContext.current = RSpecContext.context_for(example)
+            end
+
+            config.after(:each) do
+              TestContext.clear
+            end
+          end
+
+          @installed = true
+        end
+
+        def installed?
+          @installed == true
+        end
+
+        def context_for(example)
+          metadata = example.metadata
+
+          {
+            test: metadata[:description],
+            suite: metadata[:example_group][:description],
+            file: metadata[:file_path],
+            line: metadata[:line_number]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/reqcord/capture/test_context.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Capture
+    # The test that is currently running, kept per thread so parallel runners
+    # do not attribute an exchange to the wrong test.
+    module TestContext
+      THREAD_KEY = :reqcord_test_context
+
+      class << self
+        def current
+          Thread.current[THREAD_KEY] || {}
+        end
+
+        def current=(value)
+          Thread.current[THREAD_KEY] = value
+        end
+
+        def clear
+          Thread.current[THREAD_KEY] = nil
+        end
+      end
+    end
+  end
+end

data/lib/reqcord/capture.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # Capture runs inside the test process and writes to a file the generator
+  # reads afterwards. Both variables are set by `reqcord:generate`, so an
+  # ordinary test run patches nothing and writes nothing.
+  module Capture
+    class << self
+      def enabled?
+        ENV["REQCORD_CAPTURE"] == "1" &&
+          capture_file
+      end
+
+      def capture_file
+        ENV["REQCORD_CAPTURE_FILE"]
+      end
+    end
+  end
+end