reqcord 0.1.0 → 0.1.1

data/docs/configuration.md

@@ -0,0 +1,319 @@
+# `reqcord.yml` reference
+
+Reqcord reads one file, `reqcord.yml`, from the application root (`Rails.root`).
+`bin/rails reqcord:init` writes a starting point; every key is optional.
+
+```yaml
+version: 1
+
+test:
+  framework: minitest
+  paths:
+    - test/integration
+    - test/api
+
+routes:
+  prefix: /api
+
+output:
+  directory: docs/api
+  include_uncovered: false
+
+exporters:
+  - curl
+  - markdown
+  - postman
+
+variables:
+  base_url: http://localhost:3000
+
+sanitize:
+  headers:
+    Authorization: "Bearer {{token}}"
+    X-Api-Key: "{{api_key}}"
+  body:
+    password: "{{password}}"
+```
+
+## How values are resolved
+
+```text
+environment variable  >  reqcord.yml  >  Reqcord default
+```
+
+The file is **deep-merged** over the defaults: setting `sanitize.headers.X-Account-Id`
+keeps the default `Authorization` and `X-Api-Key` entries. Lists are replaced,
+not merged: an `exporters:` list is used exactly as written.
+
+The file must be a YAML mapping; anything else raises `Reqcord::ConfigurationError`
+before any test runs. YAML aliases are disabled.
+
+| Variable | Overrides |
+| --- | --- |
+| `REQCORD_TEST_FRAMEWORK` | `test.framework` |
+| `REQCORD_TEST_COMMAND` | `test.command` (and therefore `test.paths`) |
+| `REQCORD_OUTPUT` | `output.directory` |
+| `REQCORD_BASE_URL` | `variables.base_url` |
+| `RESOURCE`, `VERSION` | run-time filters, see [Filtering a run](#filtering-a-run) |
+
+`REQCORD_CAPTURE` and `REQCORD_CAPTURE_FILE` are set **by** Reqcord on the test
+process it starts; do not set them yourself. Without them an ordinary
+`bin/rails test` patches nothing and writes nothing.
+
+---
+
+## `version`
+
+```yaml
+version: 1
+```
+
+The configuration format version. Informational today; keep it at `1`.
+
+---
+
+## `test`
+
+Where the requests come from. `reqcord:generate` runs your suite in a
+subprocess with capture enabled; every request the integration tests make
+is captured, so point this at the tests that exercise the API.
+
+### `test.framework`
+
+`minitest` (default) or `rspec`. Decides two things: how the suite is run
+when only `paths` is given, and how captured examples are named — from the
+Minitest test method (`test "creates customer"`) or the RSpec example
+(`it "creates customer"`). Any other value is rejected before the run.
+
+### `test.paths`
+
+Directories, files or globs. Reqcord builds the runner:
+
+| Framework | Project has `bin/rails` | Command |
+| --- | --- | --- |
+| minitest | yes | `bin/rails test <paths…>` |
+| minitest | no | `ruby -Itest -e '<require each file>' <every *_test.rb beneath the paths>` |
+| rspec | — | `rspec <paths…>` |
+
+A directory means every `*_test.rb` (or `*_spec.rb`) beneath it; a glob such as
+`test/api/*_test.rb` is expanded by Reqcord.
+
+```yaml
+test:
+  framework: minitest
+  paths:
+    - test/api
+    - test/controllers/api
+    - test/integration
+```
+
+### `test.command`
+
+Spell the command out yourself. It wins over `paths`.
+
+```yaml
+test:
+  command: bin/rails test test/api test/integration/orders_test.rb
+```
+
+The command is split into words and executed **without a shell**: no pipes,
+`&&`, environment assignments or quoting tricks. Globs in the arguments are
+expanded by Reqcord (`test/api/*_test.rb` works). An empty string counts as
+absent.
+
+With neither `paths` nor `command`, Reqcord runs `bin/rails test`.
+
+Whatever runs must exit successfully. A failing suite aborts the run with
+`Reqcord::GenerationError` and nothing is written — documentation is only
+generated from a green suite.
+
+---
+
+## `routes`
+
+The documented surface is the application's route table (including mounted
+engines), not the captured traffic: every matching route becomes an endpoint,
+and captures are attached to it.
+
+### `routes.prefix`
+
+Default `/api`. Only routes whose path starts with the prefix are documented.
+For a mounted engine the prefix is matched against the full path
+(`/api/billing/invoices`). Set it to an empty string to document every route.
+
+```yaml
+routes:
+  prefix: /api/v2
+```
+
+Rails' own routes (`rails/…`, Active Storage, Action Mailbox, Turbo) are always
+left out. `redirect(...)` routes and plain Rack mounts cannot be documented from
+a test; they are counted as *skipped* in the report rather than dropped.
+
+### Filtering a run
+
+Filters are given per run, not in the file:
+
+```bash
+bin/rails reqcord:generate RESOURCE=customers
+bin/rails reqcord:generate RESOURCE=customers,cart
+bin/rails reqcord:generate VERSION=v2
+bin/rails reqcord:generate RESOURCE=orders VERSION=v1
+```
+
+`RESOURCE` matches the controller's last segment (`customers`), its singular
+(`cart` for `CartsController`) or the full controller path
+(`api/v2/customers`). `VERSION` matches a `v<number>` segment in the controller
+path or the route path.
+
+---
+
+## `output`
+
+### `output.directory`
+
+Default `docs/api`, relative to the application root (an absolute path is used
+as is). Override per run with `REQCORD_OUTPUT`. A run writes:
+
+```text
+<directory>/
+├── dataset.json          the canonical dataset every exporter reads
+├── README.md             index of resources and endpoints        (markdown)
+├── api/v1/customers/     one directory per controller path       (markdown)
+│   ├── index.md
+│   └── create.md
+├── curl/api/v1/customers/create.sh                                 (curl)
+└── postman/collection.json                                         (postman)
+```
+
+Directories follow the controller path, so `admin/customers` and
+`api/v1/customers` never collide.
+
+### `output.include_uncovered`
+
+Default `false`. A route no test reached with a `2xx` response is listed in
+the index under *No Successful Request Captured* and in `dataset.json` under
+`uncovered_routes`, but gets no page of its own. Set `true` to write those
+pages as well, each carrying a note that nothing was captured.
+
+---
+
+## `exporters`
+
+Which outputs to write. Default: all three.
+
+| Name | Writes |
+| --- | --- |
+| `markdown` | `README.md` plus one page per endpoint: headers, typed parameter tables, example request, cURL, one example and field table per response status |
+| `curl` | one runnable `.sh` per endpoint under `curl/`, built from the successful captured request |
+| `postman` | `postman/collection.json`, a Postman Collection v2.1 — folders per controller namespace, one request per endpoint, every captured status saved as an example, placeholders as collection variables, bearer auth at collection level. Hoppscotch imports the same file |
+
+`dataset.json` is always written. An unknown name raises
+`Reqcord::ConfigurationError` before any test runs.
+
+---
+
+## `variables`
+
+### `variables.base_url`
+
+Default `http://localhost:3000`. The host in every generated cURL and the value
+of the Postman `base_url` collection variable. A trailing slash is dropped.
+Override per run with `REQCORD_BASE_URL`.
+
+Other keys under `variables` are read but not used by the built-in exporters.
+
+---
+
+## `sanitize`
+
+Captured tests carry real credentials. Sanitization runs on every exchange
+before anything reaches the dataset, so generated files never contain them.
+
+### `sanitize.headers`
+
+Header name → replacement, matched case-insensitively, replaced **verbatim**:
+
+```yaml
+sanitize:
+  headers:
+    Authorization: "Bearer {{token}}"
+    X-Api-Key: "{{api_key}}"
+    X-Account-Id: "{{account_id}}"
+```
+
+Defaults: `Authorization: "Bearer {{token}}"` and `X-Api-Key: "{{api_key}}"`.
+
+Some headers are redacted **whether configured or not**: `Authorization`,
+`Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-Api-Key`, `X-Auth-Token`,
+`X-Csrf-Token`. Without a configured replacement the value becomes a
+placeholder named after the header (`{{cookie}}`, `{{x_auth_token}}`), and a
+`Bearer`, `Token` or `Basic` scheme is kept so the cURL stays runnable
+(`Basic {{authorization}}`).
+
+Two more things happen to headers, on requests and responses alike:
+
+* transport noise is dropped: `Host`, `User-Agent`, `Connection`, `Version`,
+  `Remote-Addr`, `Accept-Encoding`, `Cache-Control`, `Content-Length`, `Date`,
+  `ETag`, `Server-Timing`, `Transfer-Encoding`, `Vary`, `X-Request-Id`,
+  `X-Runtime`, `Referrer-Policy` and the `X-*-Options` security headers;
+* headers with an empty value are dropped.
+
+### `sanitize.body`
+
+Body key → replacement, matched case-insensitively **at any depth**, in
+request and response bodies alike. The whole value under the key is replaced,
+whatever its type.
+
+```yaml
+sanitize:
+  body:
+    password: "{{password}}"
+    payment_url: "{{payment_url}}"
+```
+
+Defaults: `password`, `password_confirmation`, `token`, `access_token`,
+`refresh_token`, `api_key`, `secret`, `client_secret` (→ `{{password}}`,
+`{{token}}`, `{{api_key}}`, `{{secret}}`).
+
+A sanitized value is what the documentation shows, so it also shapes the
+parameter tables: two logins whose passwords both became `{{password}}` are two
+examples of the same request, and the one that succeeded is the one used for
+the cURL.
+
+### Placeholders
+
+Every `{{name}}` you write is kept as-is in Markdown and cURL, listed in the
+index under *Placeholders*, and declared as a variable in the Postman
+collection — Postman's variable syntax is the same, so the collection runs as
+soon as `base_url` and `token` are filled in.
+
+---
+
+## Rake tasks
+
+| Task | Does |
+| --- | --- |
+| `bin/rails reqcord:init` | writes `reqcord.yml` (never overwrites) and creates `docs/api/` |
+| `bin/rails reqcord:generate` | collects routes, runs the suite with capture, writes every exporter, prints the report |
+| `bin/rails reqcord:routes` | lists the routes the current `prefix` (and `RESOURCE` / `VERSION`) would document |
+
+Every `generate` run ends with a reconciliation of the whole route table:
+
+```text
+[reqcord] captured 92 request(s), 87 matched a documented route
+[reqcord] captured a successful 2xx request for 14 of 16 endpoint(s)
+[reqcord] routes: 16 = 14 documented + 2 uncovered + 0 skipped
+```
+
+Each route is in exactly one bucket; a captured request that matched no
+documented route is listed, never dropped silently.
+
+## When the output looks thin
+
+| Symptom | Usual cause |
+| --- | --- |
+| `no request was captured` | the gem is not in the `:test` group of the Gemfile, or `test.paths` / `test.command` runs no integration tests |
+| many requests captured, few matched | `routes.prefix` does not cover them — the unmatched paths are printed |
+| routes documented but few covered | the tests that exercise them are not in `test.paths` (a `2xx` from a test is what makes an endpoint documented) |
+| `Test suite failed while generating` | the suite is red; fix the tests, documentation is only generated from a passing run |

data/examples/complex-spec-app/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/examples/complex-spec-app/README.md

@@ -0,0 +1,21 @@
+# complex-spec-app (RSpec)
+
+The store API of [complex-test-app](../complex-test-app), documented from
+RSpec request specs instead of Minitest. The application file is identical;
+only the specs differ, and the generated dataset lists the same 22 endpoints.
+
+```text
+app.rb                  the application (same as complex-test-app)
+spec/requests/*_spec.rb ordinary request specs
+spec/spec_helper.rb     request helpers for plain rspec-core (see spec-app)
+reqcord.yml             `test.framework: rspec`, `paths: [spec/requests]`
+docs/api/               generated Markdown, cURL scripts, Postman collection
+```
+
+## Regenerate
+
+```bash
+ruby generate.rb
+```
+
+See the endpoint tour in the [complex-test-app README](../complex-test-app/README.md).

data/examples/complex-spec-app/app.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+# The store API of complex-test-app, byte for byte, documented from RSpec
+# request specs instead of Minitest. See ../complex-test-app/app.rb for the
+# tour of what each endpoint shows.
+ENV["RAILS_ENV"] ||= "test"
+
+# Only needed because this example lives inside the Reqcord repository.
+# In your own application, `gem "reqcord"` in the Gemfile is enough.
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "rails"
+require "action_controller/railtie"
+require "reqcord"
+
+class ComplexApp < Rails::Application
+  config.root = __dir__
+  config.eager_load = false
+  config.logger = Logger.new(IO::NULL)
+  config.secret_key_base = "a" * 64
+  config.hosts.clear
+end
+
+Rails.application.initialize!
+
+module Store
+  PRODUCTS = [
+    { id: 1, sku: "TEA-001", name: "Earl Grey", category: "tea", price_cents: 1200, cost_cents: 500, tags: %w[black bergamot] },
+    { id: 2, sku: "TEA-002", name: "Sencha", category: "tea", price_cents: 1500, cost_cents: 700, tags: %w[green] },
+    { id: 3, sku: "MUG-001", name: "Stoneware Mug", category: "mugs", price_cents: 2400, cost_cents: 900, tags: %w[ceramic] },
+    { id: 4, sku: "MUG-002", name: "Travel Mug", category: "mugs", price_cents: 3200, cost_cents: 1400, tags: %w[steel insulated] }
+  ].freeze
+
+  PUBLIC_PRODUCT = %i[id sku name category price_cents tags].freeze
+
+  ORDERS = [
+    { id: 1, user_id: 1, status: "pending", currency: "USD", total_cents: 2700 },
+    { id: 2, user_id: 1, status: "shipped", currency: "USD", total_cents: 3200 },
+    { id: 3, user_id: 2, status: "pending", currency: "EUR", total_cents: 1500 }
+  ].freeze
+
+  NOTES = [
+    { id: 1, order_id: 1, body: "Leave at the door", author: "ada" },
+    { id: 2, order_id: 1, body: "Gift wrap please", author: "ada" }
+  ].freeze
+
+  PROFILE = { id: 1, name: "Ada Lovelace", email: "ada@example.com", locale: "en" }.freeze
+  LOCALES = %w[en tr].freeze
+
+  CART_ITEMS = [
+    { sku: "TEA-001", name: "Earl Grey", quantity: 2, unit_price_cents: 1200 },
+    { sku: "MUG-001", name: "Stoneware Mug", quantity: 1, unit_price_cents: 2400 }
+  ].freeze
+  PAYMENT_METHODS = %w[card bank_transfer].freeze
+end
+
+module Api
+  module V1
+    class BaseController < ActionController::API
+      private
+
+      def authenticate!
+        return if request.headers["Authorization"].present?
+
+        render json: { error: "Unauthorized" }, status: :unauthorized
+      end
+
+      def not_found
+        render json: { error: "Not Found" }, status: :not_found
+      end
+    end
+
+    class HomeController < BaseController
+      def index
+        render json: { name: "Store API", version: "v1", links: { products: "/api/v1/products", orders: "/api/v1/orders" } }
+      end
+    end
+
+    class AuthController < BaseController
+      def login
+        if params[:email] == "ada@example.com" && params[:password] == "correct-horse-battery"
+          render json: { token: "tok_live_9f8e7d6c", token_type: "Bearer", expires_in: 3600 }
+        else
+          render json: { error: "Invalid email or password" }, status: :unauthorized
+        end
+      end
+    end
+
+    class ProfilesController < BaseController
+      before_action :authenticate!
+
+      def show
+        render json: Store::PROFILE
+      end
+
+      def update
+        attributes = params.require(:profile).permit(:name, :locale).to_h.symbolize_keys
+
+        if attributes.key?(:locale) && !Store::LOCALES.include?(attributes[:locale])
+          return render(json: { errors: { locale: ["is not included in the list"] } }, status: :unprocessable_entity)
+        end
+
+        render json: Store::PROFILE.merge(attributes)
+      end
+    end
+
+    class ProductsController < BaseController
+      def index
+        products = Store::PRODUCTS
+        category = params.dig(:filter, :category)
+        products = products.select { |product| product[:category] == category } if category.present?
+        products = products.sort_by { |product| product[:price_cents] } if params[:sort] == "price_asc"
+        products = products.sort_by { |product| -product[:price_cents] } if params[:sort] == "price_desc"
+
+        page = params.fetch(:page, 1).to_i
+        per_page = params.fetch(:per_page, 2).to_i
+        slice = products.each_slice(per_page).to_a[page - 1] || []
+
+        render json: {
+          data: slice.map { |product| product.slice(*Store::PUBLIC_PRODUCT) },
+          meta: { page: page, per_page: per_page, total: products.size }
+        }
+      end
+
+      def show
+        product = Store::PRODUCTS.find { |candidate| candidate[:id] == params[:id].to_i }
+
+        return not_found unless product
+
+        render json: product.slice(*Store::PUBLIC_PRODUCT)
+      end
+
+      def search
+        query = params[:q].to_s.strip
+
+        return render(json: { error: "q is required" }, status: :bad_request) if query.empty?
+
+        matches = Store::PRODUCTS.select { |product| product[:name].downcase.include?(query.downcase) }
+
+        render json: { query: query, results: matches.map { |product| product.slice(*Store::PUBLIC_PRODUCT) } }
+      end
+    end
+
+    class OrdersController < BaseController
+      before_action :authenticate!
+      before_action :find_order, only: %i[show cancel destroy]
+
+      def index
+        orders = Store::ORDERS.select { |order| order[:user_id] == 1 }
+        orders = orders.select { |order| order[:status] == params[:status] } if params[:status].present?
+
+        render json: orders
+      end
+
+      def show
+        return render(json: { error: "Forbidden" }, status: :forbidden) unless @order[:user_id] == 1
+
+        render json: @order
+      end
+
+      def create
+        attributes = params.require(:order)
+                           .permit(line_items: %i[sku quantity], shipping_address: %i[line1 city country])
+                           .to_h.deep_symbolize_keys
+        items = Array(attributes[:line_items])
+
+        return render(json: { errors: { line_items: ["can't be blank"] } }, status: :unprocessable_entity) if items.empty?
+
+        lines = items.map do |item|
+          product = Store::PRODUCTS.find { |candidate| candidate[:sku] == item[:sku] }
+
+          return render(json: { errors: { sku: ["#{item[:sku]} is not a known product"] } }, status: :unprocessable_entity) unless product
+
+          quantity = item[:quantity].to_i
+          {
+            sku: product[:sku], name: product[:name], quantity: quantity,
+            unit_price_cents: product[:price_cents], subtotal_cents: product[:price_cents] * quantity
+          }
+        end
+
+        render json: {
+          id: 4, status: "pending", currency: "USD",
+          total_cents: lines.sum { |line| line[:subtotal_cents] },
+          line_items: lines,
+          shipping_address: attributes[:shipping_address]
+        }, status: :created
+      end
+
+      def cancel
+        if @order[:status] == "shipped"
+          return render(json: { error: "Shipped orders cannot be cancelled" }, status: :conflict)
+        end
+
+        render json: @order.merge(status: "cancelled")
+      end
+
+      def destroy
+        head :no_content
+      end
+
+      private
+
+      def find_order
+        @order = Store::ORDERS.find { |order| order[:id] == params[:id].to_i }
+
+        not_found unless @order
+      end
+    end
+
+    class NotesController < BaseController
+      before_action :authenticate!
+      before_action :find_order
+
+      def index
+        render json: Store::NOTES.select { |note| note[:order_id] == @order[:id] }
+      end
+
+      def create
+        body = params.dig(:note, :body).to_s
+
+        return render(json: { errors: { body: ["can't be blank"] } }, status: :unprocessable_entity) if body.empty?
+
+        render json: { id: 3, order_id: @order[:id], body: body, author: "ada" }, status: :created
+      end
+
+      private
+
+      def find_order
+        @order = Store::ORDERS.find { |order| order[:id] == params[:order_id].to_i }
+
+        not_found unless @order
+      end
+    end
+
+    class CartsController < BaseController
+      before_action :authenticate!
+
+      def show
+        render json: cart
+      end
+
+      def checkout
+        method = params[:payment_method].to_s
+
+        unless Store::PAYMENT_METHODS.include?(method)
+          return render(json: { errors: { payment_method: ["is not included in the list"] } }, status: :unprocessable_entity)
+        end
+
+        render json: { id: 5, status: "pending", payment_method: method, total_cents: cart[:total_cents], line_items: cart[:items] },
+               status: :created
+      end
+
+      private
+
+      def cart
+        { items: Store::CART_ITEMS, total_cents: Store::CART_ITEMS.sum { |item| item[:quantity] * item[:unit_price_cents] } }
+      end
+    end
+
+    class CartItemsController < BaseController
+      before_action :authenticate!
+
+      def create
+        attributes = params.require(:item).permit(:sku, :quantity).to_h.symbolize_keys
+        product = Store::PRODUCTS.find { |candidate| candidate[:sku] == attributes[:sku] }
+
+        return render(json: { errors: { sku: ["#{attributes[:sku]} is not a known product"] } }, status: :unprocessable_entity) unless product
+
+        render json: { sku: product[:sku], name: product[:name], quantity: attributes[:quantity].to_i, unit_price_cents: product[:price_cents] },
+               status: :created
+      end
+
+      def destroy
+        return not_found unless Store::CART_ITEMS.any? { |item| item[:sku] == params[:sku] }
+
+        head :no_content
+      end
+    end
+
+    module Admin
+      class ProductsController < BaseController
+        before_action :require_api_key
+
+        def index
+          render json: Store::PRODUCTS
+        end
+
+        def create
+          attributes = params.require(:product).permit(:sku, :name, :category, :price_cents).to_h.symbolize_keys
+
+          if attributes[:sku].to_s.empty? || attributes[:name].to_s.empty?
+            return render(json: { errors: { sku: ["can't be blank"] } }, status: :unprocessable_entity)
+          end
+
+          if Store::PRODUCTS.any? { |product| product[:sku] == attributes[:sku] }
+            return render(json: { error: "sku #{attributes[:sku]} already exists" }, status: :conflict)
+          end
+
+          render json: { id: 5, cost_cents: 0, tags: [], **attributes }, status: :created
+        end
+
+        def destroy
+          return not_found unless Store::PRODUCTS.any? { |product| product[:id] == params[:id].to_i }
+
+          head :no_content
+        end
+
+        private
+
+        def require_api_key
+          return if request.headers["X-Api-Key"].present?
+
+          render json: { error: "API key required" }, status: :unauthorized
+        end
+      end
+    end
+  end
+
+  module V2
+    class ProductsController < ActionController::API
+      def index
+        start = params[:cursor].present? ? 2 : 0
+        items = Store::PRODUCTS[start, 2].map { |product| product.slice(*Store::PUBLIC_PRODUCT).merge(price: format("%.2f", product[:price_cents] / 100.0)) }
+
+        render json: { items: items, next_cursor: start.zero? ? "eyJpZCI6Mn0" : nil }
+      end
+    end
+  end
+end
+
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      root to: "home#index"
+
+      post "auth/login", to: "auth#login"
+
+      resource :profile, only: %i[show update]
+
+      resources :products, only: %i[index show] do
+        get :search, on: :collection
+      end
+
+      resources :orders, only: %i[index show create destroy] do
+        post :cancel, on: :member
+        resources :notes, only: %i[index create]
+      end
+
+      resource :cart, only: :show do
+        post :checkout
+        resources :items, only: %i[create destroy], controller: "cart_items", param: :sku
+      end
+
+      namespace :admin do
+        resources :products, only: %i[index create destroy]
+      end
+    end
+
+    namespace :v2 do
+      resources :products, only: :index
+    end
+  end
+end