reqcord 0.1.0 → 0.1.1

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

@@ -0,0 +1,28 @@
+version: 1
+
+test:
+  framework: rspec
+  paths:
+    - spec/requests
+
+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-spec-app/spec/requests/admin_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Admin and v2", type: :request do
+  let(:api_key) { { "X-Api-Key" => "sk_live_super-secret-key" } }
+
+  it "admin lists products with costs" do
+    get "/api/v1/admin/products", headers: api_key, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "admin requires an api key" do
+    get "/api/v1/admin/products", as: :json
+
+    expect(response.status).to eq(401)
+  end
+
+  it "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
+
+    expect(response.status).to eq(201)
+  end
+
+  it "admin rejects a product without a sku" do
+    post "/api/v1/admin/products", params: { product: { sku: "", name: "Nameless" } }, headers: api_key, as: :json
+
+    expect(response.status).to eq(422)
+  end
+
+  it "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
+
+    expect(response.status).to eq(409)
+  end
+
+  it "admin deletes a product" do
+    delete "/api/v1/admin/products/4", headers: api_key, as: :json
+
+    expect(response.status).to eq(204)
+  end
+
+  it "admin cannot delete an unknown product" do
+    delete "/api/v1/admin/products/999", headers: api_key, as: :json
+
+    expect(response.status).to eq(404)
+  end
+
+  it "v2 lists products" do
+    get "/api/v2/products", as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "v2 follows a cursor" do
+    get "/api/v2/products", params: { cursor: "eyJpZCI6Mn0" }, as: :json
+
+    expect(response.status).to eq(200)
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Cart", type: :request do
+  let(:auth) { { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" } }
+
+  it "shows the cart" do
+    get "/api/v1/cart", headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "adds an item to the cart" do
+    post "/api/v1/cart/items", params: { item: { sku: "TEA-002", quantity: 3 } }, headers: auth, as: :json
+
+    expect(response.status).to eq(201)
+  end
+
+  it "rejects an unknown sku" do
+    post "/api/v1/cart/items", params: { item: { sku: "TEA-999", quantity: 1 } }, headers: auth, as: :json
+
+    expect(response.status).to eq(422)
+  end
+
+  it "removes an item from the cart" do
+    delete "/api/v1/cart/items/TEA-001", headers: auth, as: :json
+
+    expect(response.status).to eq(204)
+  end
+
+  it "cannot remove an item that is not in the cart" do
+    delete "/api/v1/cart/items/MUG-002", headers: auth, as: :json
+
+    expect(response.status).to eq(404)
+  end
+
+  it "checks out with a card" do
+    post "/api/v1/cart/checkout", params: { payment_method: "card" }, headers: auth, as: :json
+
+    expect(response.status).to eq(201)
+  end
+
+  it "checks out with a bank transfer" do
+    post "/api/v1/cart/checkout", params: { payment_method: "bank_transfer" }, headers: auth, as: :json
+
+    expect(response.status).to eq(201)
+  end
+
+  it "rejects an unknown payment method" do
+    post "/api/v1/cart/checkout", params: { payment_method: "cash" }, headers: auth, as: :json
+
+    expect(response.status).to eq(422)
+  end
+
+  it "cart requires authentication" do
+    get "/api/v1/cart", as: :json
+
+    expect(response.status).to eq(401)
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Home and auth", type: :request do
+  let(:auth) { { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" } }
+
+  it "root describes the api" do
+    get "/api/v1", as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "logs in with a form" do
+    post "/api/v1/auth/login", params: { email: "ada@example.com", password: "correct-horse-battery" }
+
+    expect(response.status).to eq(200)
+  end
+
+  it "rejects a wrong password" do
+    post "/api/v1/auth/login", params: { email: "ada@example.com", password: "wrong" }
+
+    expect(response.status).to eq(401)
+  end
+
+  it "shows the profile" do
+    get "/api/v1/profile", headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "updates the profile" do
+    patch "/api/v1/profile", params: { profile: { name: "Ada L.", locale: "tr" } }, headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "rejects an unknown locale" do
+    patch "/api/v1/profile", params: { profile: { locale: "xx" } }, headers: auth, as: :json
+
+    expect(response.status).to eq(422)
+  end
+
+  it "profile requires authentication" do
+    get "/api/v1/profile", as: :json
+
+    expect(response.status).to eq(401)
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Orders", type: :request do
+  let(:auth) { { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" } }
+
+  let(:order_payload) do
+    {
+      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
+
+  it "lists orders" do
+    get "/api/v1/orders", headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "lists pending orders" do
+    get "/api/v1/orders", params: { status: "pending" }, headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "lists shipped orders" do
+    get "/api/v1/orders", params: { status: "shipped" }, headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "shows an order" do
+    get "/api/v1/orders/1", headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "hides another customer's order" do
+    get "/api/v1/orders/3", headers: auth, as: :json
+
+    expect(response.status).to eq(403)
+  end
+
+  it "returns not found for an unknown order" do
+    get "/api/v1/orders/999", headers: auth, as: :json
+
+    expect(response.status).to eq(404)
+  end
+
+  it "creates an order" do
+    post "/api/v1/orders", params: order_payload, headers: auth, as: :json
+
+    expect(response.status).to eq(201)
+  end
+
+  it "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
+
+    expect(response.status).to eq(201)
+  end
+
+  it "rejects an order without line items" do
+    post "/api/v1/orders", params: { order: { line_items: [] } }, headers: auth, as: :json
+
+    expect(response.status).to eq(422)
+  end
+
+  it "rejects an unknown sku" do
+    post "/api/v1/orders", params: { order: { line_items: [{ sku: "TEA-999", quantity: 1 }] } }, headers: auth, as: :json
+
+    expect(response.status).to eq(422)
+  end
+
+  it "cancels a pending order" do
+    post "/api/v1/orders/1/cancel", headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "cannot cancel a shipped order" do
+    post "/api/v1/orders/2/cancel", headers: auth, as: :json
+
+    expect(response.status).to eq(409)
+  end
+
+  it "deletes an order" do
+    delete "/api/v1/orders/1", headers: auth, as: :json
+
+    expect(response.status).to eq(204)
+  end
+
+  it "orders require authentication" do
+    get "/api/v1/orders", as: :json
+
+    expect(response.status).to eq(401)
+  end
+
+  it "lists the notes of an order" do
+    get "/api/v1/orders/1/notes", headers: auth, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "adds a note to an order" do
+    post "/api/v1/orders/1/notes", params: { note: { body: "Ring the bell twice" } }, headers: auth, as: :json
+
+    expect(response.status).to eq(201)
+  end
+
+  it "rejects an empty note" do
+    post "/api/v1/orders/1/notes", params: { note: { body: "" } }, headers: auth, as: :json
+
+    expect(response.status).to eq(422)
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Products", type: :request do
+  it "lists products" do
+    get "/api/v1/products", as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "filters products by category" do
+    get "/api/v1/products", params: { filter: { category: "tea" } }, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "filters mugs" do
+    get "/api/v1/products", params: { filter: { category: "mugs" } }, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "sorts by price ascending" do
+    get "/api/v1/products", params: { sort: "price_asc" }, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "sorts by price descending" do
+    get "/api/v1/products", params: { sort: "price_desc" }, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "paginates" do
+    get "/api/v1/products", params: { page: 2, per_page: 2 }, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "shows a product" do
+    get "/api/v1/products/3", as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "returns not found for an unknown product" do
+    get "/api/v1/products/999", as: :json
+
+    expect(response.status).to eq(404)
+  end
+
+  it "searches products" do
+    get "/api/v1/products/search", params: { q: "mug" }, as: :json
+
+    expect(response.status).to eq(200)
+  end
+
+  it "search needs a query" do
+    get "/api/v1/products/search", as: :json
+
+    expect(response.status).to eq(400)
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../app"
+
+require "rspec/core"
+require "action_dispatch/testing/integration"
+
+RSpec.configure do |config|
+  # What rspec-rails would give you as `type: :request`; spelled out here so
+  # the example runs with plain rspec-core.
+  config.include ActionDispatch::Integration::Runner, type: :request
+  config.include ActionDispatch::IntegrationTest::Behavior, type: :request
+
+  config.before(:each, type: :request) { integration_session }
+
+  config.expect_with(:rspec) { |expectations| expectations.syntax = :expect }
+end

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

@@ -0,0 +1,40 @@
+# complex-test-app (Minitest)
+
+A store API in one file, with ordinary Minitest integration tests, chosen to
+show the harder things Reqcord documents. Start with [test-app](../test-app)
+if you want the gentle version.
+
+| Endpoint | What it shows in the output |
+| --- | --- |
+| `GET /api/v1` | `root` inside a namespace, titled "Home" |
+| `POST /api/v1/auth/login` | a **form** post (`urlencoded` in Postman, `--data 'email=…'` in cURL); the `token` in the response is sanitized to `{{token}}` |
+| `GET` / `PATCH /api/v1/profile` | singular `resource`; `PATCH` and `PUT` folded into one page |
+| `GET /api/v1/products` | nested query `filter[category]`, an optional `sort` with a closed set (`"price_asc" \| "price_desc"`), `page` / `per_page` |
+| `GET /api/v1/products/search` | collection action, `400` without `q` |
+| `POST /api/v1/orders` | an array body: `order.line_items[].sku`, `order.shipping_address.city` |
+| `GET /api/v1/orders/:id` | `403` for another customer's order, `404` |
+| `POST /api/v1/orders/:id/cancel` | member action, `409` once shipped |
+| `GET /api/v1/orders/:order_id/notes` | nested resource, `order_id` as a path parameter |
+| `GET /api/v1/cart` | singular `resource :cart` — one record, no id |
+| `POST` / `DELETE /api/v1/cart/items/:sku` | items nested under the cart, addressed by `sku` (`param: :sku`) |
+| `POST /api/v1/cart/checkout` | custom action on a singular resource ("Checkout Cart"), `payment_method` as `"bank_transfer" \| "card"` |
+| `/api/v1/admin/products` | a second credential (`X-Api-Key` → `{{api_key}}`), its own `admin` folder, `409` on a duplicate sku |
+| `GET /api/v2/products` | a second API version next to the first: `VERSION=v2 ruby generate.rb` |
+
+Every route is covered by a test, so the report ends in
+`routes: 22 = 22 documented + 0 uncovered + 0 skipped`.
+
+```text
+app.rb                     the application
+test/integration/*_test.rb ordinary integration tests
+reqcord.yml                paths, prefix, two sanitized headers and two body keys
+docs/api/                  generated Markdown, cURL scripts, Postman collection
+```
+
+## Regenerate
+
+```bash
+ruby generate.rb
+RESOURCE=orders,notes ruby generate.rb
+VERSION=v2 ruby generate.rb
+```