reqcord 0.1.0 → 0.1.1

data/examples/complex-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/complex-test-app/reqcord.yml

@@ -0,0 +1,28 @@
+version: 1
+
+test:
+  framework: minitest
+  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}}"
+    X-Api-Key: "{{api_key}}"
+  body:
+    password: "{{password}}"
+    token: "{{token}}"

data/examples/complex-test-app/test/integration/admin_test.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../../app"
+require "minitest/autorun"
+
+class AdminTest < ActionDispatch::IntegrationTest
+  def api_key
+    { "X-Api-Key" => "sk_live_super-secret-key" }
+  end
+
+  test "admin lists products with costs" do
+    get "/api/v1/admin/products", headers: api_key, as: :json
+
+    assert_response :ok
+  end
+
+  test "admin requires an api key" do
+    get "/api/v1/admin/products", as: :json
+
+    assert_response :unauthorized
+  end
+
+  test "admin creates a product" do
+    post "/api/v1/admin/products",
+         params: { product: { sku: "TEA-003", name: "Jasmine", category: "tea", price_cents: 1400 } },
+         headers: api_key,
+         as: :json
+
+    assert_response :created
+  end
+
+  test "admin rejects a product without a sku" do
+    post "/api/v1/admin/products", params: { product: { sku: "", name: "Nameless" } }, headers: api_key, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "admin rejects a duplicate sku" do
+    post "/api/v1/admin/products",
+         params: { product: { sku: "TEA-001", name: "Earl Grey again", category: "tea", price_cents: 1200 } },
+         headers: api_key,
+         as: :json
+
+    assert_response :conflict
+  end
+
+  test "admin deletes a product" do
+    delete "/api/v1/admin/products/4", headers: api_key, as: :json
+
+    assert_response :no_content
+  end
+
+  test "admin cannot delete an unknown product" do
+    delete "/api/v1/admin/products/999", headers: api_key, as: :json
+
+    assert_response :not_found
+  end
+
+  test "v2 lists products" do
+    get "/api/v2/products", as: :json
+
+    assert_response :ok
+  end
+
+  test "v2 follows a cursor" do
+    get "/api/v2/products", params: { cursor: "eyJpZCI6Mn0" }, as: :json
+
+    assert_response :ok
+  end
+end

data/examples/complex-test-app/test/integration/cart_test.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../../app"
+require "minitest/autorun"
+
+class CartTest < ActionDispatch::IntegrationTest
+  def auth
+    { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" }
+  end
+
+  test "shows the cart" do
+    get "/api/v1/cart", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "adds an item to the cart" do
+    post "/api/v1/cart/items", params: { item: { sku: "TEA-002", quantity: 3 } }, headers: auth, as: :json
+
+    assert_response :created
+  end
+
+  test "rejects an unknown sku" do
+    post "/api/v1/cart/items", params: { item: { sku: "TEA-999", quantity: 1 } }, headers: auth, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "removes an item from the cart" do
+    delete "/api/v1/cart/items/TEA-001", headers: auth, as: :json
+
+    assert_response :no_content
+  end
+
+  test "cannot remove an item that is not in the cart" do
+    delete "/api/v1/cart/items/MUG-002", headers: auth, as: :json
+
+    assert_response :not_found
+  end
+
+  test "checks out with a card" do
+    post "/api/v1/cart/checkout", params: { payment_method: "card" }, headers: auth, as: :json
+
+    assert_response :created
+  end
+
+  test "checks out with a bank transfer" do
+    post "/api/v1/cart/checkout", params: { payment_method: "bank_transfer" }, headers: auth, as: :json
+
+    assert_response :created
+  end
+
+  test "rejects an unknown payment method" do
+    post "/api/v1/cart/checkout", params: { payment_method: "cash" }, headers: auth, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "cart requires authentication" do
+    get "/api/v1/cart", as: :json
+
+    assert_response :unauthorized
+  end
+end

data/examples/complex-test-app/test/integration/home_and_auth_test.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../../app"
+require "minitest/autorun"
+
+class HomeAndAuthTest < ActionDispatch::IntegrationTest
+  def auth
+    { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" }
+  end
+
+  test "root describes the api" do
+    get "/api/v1", as: :json
+
+    assert_response :ok
+  end
+
+  # A form post, not JSON: the documentation must keep it a form.
+  test "logs in with a form" do
+    post "/api/v1/auth/login", params: { email: "ada@example.com", password: "correct-horse-battery" }
+
+    assert_response :ok
+  end
+
+  test "rejects a wrong password" do
+    post "/api/v1/auth/login", params: { email: "ada@example.com", password: "wrong" }
+
+    assert_response :unauthorized
+  end
+
+  test "shows the profile" do
+    get "/api/v1/profile", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "updates the profile" do
+    patch "/api/v1/profile", params: { profile: { name: "Ada L.", locale: "tr" } }, headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "rejects an unknown locale" do
+    patch "/api/v1/profile", params: { profile: { locale: "xx" } }, headers: auth, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "profile requires authentication" do
+    get "/api/v1/profile", as: :json
+
+    assert_response :unauthorized
+  end
+end

data/examples/complex-test-app/test/integration/orders_test.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../../app"
+require "minitest/autorun"
+
+class OrdersTest < ActionDispatch::IntegrationTest
+  def auth
+    { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" }
+  end
+
+  def order_payload
+    {
+      order: {
+        line_items: [
+          { sku: "TEA-001", quantity: 2 },
+          { sku: "MUG-001", quantity: 1 }
+        ],
+        shipping_address: { line1: "1 Analytical Engine Way", city: "London", country: "GB" }
+      }
+    }
+  end
+
+  test "lists orders" do
+    get "/api/v1/orders", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "lists pending orders" do
+    get "/api/v1/orders", params: { status: "pending" }, headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "lists shipped orders" do
+    get "/api/v1/orders", params: { status: "shipped" }, headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "shows an order" do
+    get "/api/v1/orders/1", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "hides another customer's order" do
+    get "/api/v1/orders/3", headers: auth, as: :json
+
+    assert_response :forbidden
+  end
+
+  test "returns not found for an unknown order" do
+    get "/api/v1/orders/999", headers: auth, as: :json
+
+    assert_response :not_found
+  end
+
+  test "creates an order" do
+    post "/api/v1/orders", params: order_payload, headers: auth, as: :json
+
+    assert_response :created
+  end
+
+  test "creates a single item order" do
+    post "/api/v1/orders",
+         params: { order: { line_items: [{ sku: "MUG-002", quantity: 1 }], shipping_address: { line1: "Piazza", city: "Rome", country: "IT" } } },
+         headers: auth,
+         as: :json
+
+    assert_response :created
+  end
+
+  test "rejects an order without line items" do
+    post "/api/v1/orders", params: { order: { line_items: [] } }, headers: auth, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "rejects an unknown sku" do
+    post "/api/v1/orders", params: { order: { line_items: [{ sku: "TEA-999", quantity: 1 }] } }, headers: auth, as: :json
+
+    assert_response :unprocessable_entity
+  end
+
+  test "cancels a pending order" do
+    post "/api/v1/orders/1/cancel", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "cannot cancel a shipped order" do
+    post "/api/v1/orders/2/cancel", headers: auth, as: :json
+
+    assert_response :conflict
+  end
+
+  test "deletes an order" do
+    delete "/api/v1/orders/1", headers: auth, as: :json
+
+    assert_response :no_content
+  end
+
+  test "orders require authentication" do
+    get "/api/v1/orders", as: :json
+
+    assert_response :unauthorized
+  end
+
+  test "lists the notes of an order" do
+    get "/api/v1/orders/1/notes", headers: auth, as: :json
+
+    assert_response :ok
+  end
+
+  test "adds a note to an order" do
+    post "/api/v1/orders/1/notes", params: { note: { body: "Ring the bell twice" } }, headers: auth, as: :json
+
+    assert_response :created
+  end
+
+  test "rejects an empty note" do
+    post "/api/v1/orders/1/notes", params: { note: { body: "" } }, headers: auth, as: :json
+
+    assert_response :unprocessable_entity
+  end
+end

data/examples/complex-test-app/test/integration/products_test.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../../app"
+require "minitest/autorun"
+
+class ProductsTest < ActionDispatch::IntegrationTest
+  test "lists products" do
+    get "/api/v1/products", as: :json
+
+    assert_response :ok
+  end
+
+  test "filters products by category" do
+    get "/api/v1/products", params: { filter: { category: "tea" } }, as: :json
+
+    assert_response :ok
+  end
+
+  test "filters mugs" do
+    get "/api/v1/products", params: { filter: { category: "mugs" } }, as: :json
+
+    assert_response :ok
+  end
+
+  test "sorts by price ascending" do
+    get "/api/v1/products", params: { sort: "price_asc" }, as: :json
+
+    assert_response :ok
+  end
+
+  test "sorts by price descending" do
+    get "/api/v1/products", params: { sort: "price_desc" }, as: :json
+
+    assert_response :ok
+  end
+
+  test "paginates" do
+    get "/api/v1/products", params: { page: 2, per_page: 2 }, as: :json
+
+    assert_response :ok
+  end
+
+  test "shows a product" do
+    get "/api/v1/products/3", as: :json
+
+    assert_response :ok
+  end
+
+  test "returns not found for an unknown product" do
+    get "/api/v1/products/999", as: :json
+
+    assert_response :not_found
+  end
+
+  test "searches products" do
+    get "/api/v1/products/search", params: { q: "mug" }, as: :json
+
+    assert_response :ok
+  end
+
+  test "search needs a query" do
+    get "/api/v1/products/search", as: :json
+
+    assert_response :bad_request
+  end
+end

data/examples/reqcord.yml

@@ -0,0 +1,58 @@
+# Reqcord configuration. Copy this file to your application root as
+# `reqcord.yml`, or generate it with `bin/rails reqcord:init`.
+#
+# Precedence: environment variables > reqcord.yml > Reqcord defaults.
+# Every key is documented in docs/configuration.md.
+
+version: 1
+
+test:
+  # minitest or rspec.
+  framework: minitest
+
+  # Where the tests that exercise your API live. Reqcord picks the runner:
+  # `bin/rails test <paths>` in a Rails app, `rspec <paths>` for request
+  # specs, a plain Ruby runner when there is no bin/rails.
+  paths:
+    - test/integration
+
+  # Or spell the command out yourself; it wins over `paths`. Globs expand.
+  # command: bin/rails test test/integration test/api
+
+routes:
+  # Only routes under this prefix are documented. Filter a single run with
+  # RESOURCE=customers,cart or VERSION=v2 instead of editing this file.
+  prefix: /api
+
+output:
+  # Relative to the application root. Override per run with REQCORD_OUTPUT.
+  directory: docs/api
+
+  # Routes no test reached with a 2xx are listed in the index either way;
+  # `true` also writes a page for each of them.
+  include_uncovered: false
+
+# markdown: pages under docs/api, curl: one runnable .sh per endpoint,
+# postman: postman/collection.json (import into Postman or Hoppscotch).
+exporters:
+  - curl
+  - markdown
+  - postman
+
+variables:
+  # Used as the host in every generated cURL and as the Postman `base_url`
+  # variable. Override with REQCORD_BASE_URL.
+  base_url: http://localhost:3000
+
+sanitize:
+  # Captured header values are replaced with these, verbatim. Authorization,
+  # Cookie and X-Api-Key are always redacted, configured here or not.
+  headers:
+    Authorization: "Bearer {{token}}"
+    X-Api-Key: "{{api_key}}"
+    X-Account-Id: "{{account_id}}"
+
+  # Body keys, matched at any depth, in requests and responses alike.
+  body:
+    password: "{{password}}"
+    access_token: "{{token}}"

data/examples/spec-app/.rspec

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

data/examples/spec-app/README.md

@@ -0,0 +1,36 @@
+# spec-app (RSpec)
+
+The same API as [test-app](../test-app), documented from RSpec request specs
+instead of Minitest. The generated dataset is identical in shape: the test
+framework only decides how examples are named.
+
+```text
+app.rb                            the application (customers, users, tasks)
+spec/requests/*_spec.rb           ordinary request specs
+spec/spec_helper.rb               request helpers (see the note below)
+reqcord.yml                       `test.framework: rspec`
+docs/api/                         generated Markdown, cURL scripts and Postman
+                                  collection — the same files test-app gets
+```
+
+## Regenerate
+
+```bash
+ruby generate.rb
+```
+
+## Notes
+
+This example runs on plain `rspec-core`, so `spec_helper.rb` includes the
+ActionDispatch request helpers itself and the specs assert
+`response.status`. An application using `rspec-rails` gets `type: :request`
+and `have_http_status` for free and needs none of that.
+
+The only Reqcord-facing difference from test-app is one line in `reqcord.yml`:
+
+```yaml
+test:
+  framework: rspec
+  paths:
+    - spec/requests
+```