reqcord 0.1.1 → 0.1.3

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

@@ -1,384 +0,0 @@
-# frozen_string_literal: true
-
-# A store API in one file: closer to a real application than test-app, so the
-# generated documentation shows the harder cases.
-#
-#   GET  /api/v1                          root inside a namespace ("Home")
-#   POST /api/v1/auth/login               form-encoded, token in the response body
-#   GET|PATCH /api/v1/profile             singular resource, PATCH and PUT folded
-#   GET  /api/v1/products                 filter[category], sort, page, per_page
-#   GET  /api/v1/products/search          collection action, 400 without q
-#   GET  /api/v1/orders/:id               403 for someone else's order
-#   POST /api/v1/orders                   line_items[] and a nested address
-#   POST /api/v1/orders/:id/cancel        409 once shipped
-#   GET  /api/v1/orders/:order_id/notes   nested resource
-#   GET  /api/v1/cart                     singular resource with nested items
-#   POST /api/v1/cart/items               add by sku, DELETE /cart/items/:sku
-#   POST /api/v1/cart/checkout            payment_method: "card" | "bank_transfer"
-#   */api/v1/admin/products               X-Api-Key, 409 on a duplicate sku
-#   GET  /api/v2/products                 a second API version, cursor paging
-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
-      # A classic form login: the test posts a form, not JSON.
-      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
-
-    # Nested under an order: /api/v1/orders/:order_id/notes
-    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
-
-    # `resource :cart`: one cart per customer, no id in the path.
-    class CartsController < BaseController
-      before_action :authenticate!
-
-      def show
-        render json: cart
-      end
-
-      # Turns the cart into an order.
-      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
-
-    # Nested under the cart and addressed by sku: /api/v1/cart/items/:sku
-    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
-      # A different credential (X-Api-Key) and a fuller view of the same data.
-      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
-      # v2 pages by cursor instead of page numbers.
-      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

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

@@ -1,104 +0,0 @@
-# API Documentation
-
-Generated by Reqcord from the application's integration tests.
-
-Base URL: `http://localhost:3000`
-
-## Placeholders
-
-| Header | Replace with |
-| --- | --- |
-| Authorization | `Bearer {{token}}` |
-| X-Api-Key | `{{api_key}}` |
-
-## Products
-
-Namespace: `api/v1/admin`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1/admin/products`](api/v1/admin/products/list.md) | List Products |
-| `POST` | [`/api/v1/admin/products`](api/v1/admin/products/create.md) | Create Product |
-| `DELETE` | [`/api/v1/admin/products/:id`](api/v1/admin/products/destroy.md) | Delete Product |
-
-## Auth
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `POST` | [`/api/v1/auth/login`](api/v1/auth/login.md) | Login |
-
-## Cart Items
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `POST` | [`/api/v1/cart/items`](api/v1/cart-items/create.md) | Create Cart Item |
-| `DELETE` | [`/api/v1/cart/items/:sku`](api/v1/cart-items/destroy.md) | Delete Cart Item |
-
-## Carts
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1/cart`](api/v1/carts/show.md) | Get Cart |
-| `POST` | [`/api/v1/cart/checkout`](api/v1/carts/checkout.md) | Checkout Cart |
-
-## Home
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1`](api/v1/home/list.md) | Home |
-
-## Notes
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1/orders/:order_id/notes`](api/v1/notes/list.md) | List Notes |
-| `POST` | [`/api/v1/orders/:order_id/notes`](api/v1/notes/create.md) | Create Note |
-
-## Orders
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1/orders`](api/v1/orders/list.md) | List Orders |
-| `POST` | [`/api/v1/orders`](api/v1/orders/create.md) | Create Order |
-| `DELETE` | [`/api/v1/orders/:id`](api/v1/orders/destroy.md) | Delete Order |
-| `GET` | [`/api/v1/orders/:id`](api/v1/orders/show.md) | Get Order |
-| `POST` | [`/api/v1/orders/:id/cancel`](api/v1/orders/cancel.md) | Cancel Order |
-
-## Products
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1/products`](api/v1/products/list.md) | List Products |
-| `GET` | [`/api/v1/products/:id`](api/v1/products/show.md) | Get Product |
-| `GET` | [`/api/v1/products/search`](api/v1/products/search.md) | Search Products |
-
-## Profiles
-
-Namespace: `api/v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1/profile`](api/v1/profiles/show.md) | Get Profile |
-| `PATCH` | [`/api/v1/profile`](api/v1/profiles/update.md) | Update Profile |
-
-## Products
-
-Namespace: `api/v2`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v2/products`](api/v2/products/list.md) | List Products |

data/examples/complex-test-app/docs/api/api/v1/admin/products/create.md

@@ -1,117 +0,0 @@
-# Create Product
-
-`POST /api/v1/admin/products`
-
-Namespace: `api/v1/admin`
-
-## Headers
-
-| Header | Value |
-| --- | --- |
-| X-Api-Key | `{{api_key}}` |
-| Content-Type | `application/json` |
-| Accept | `application/json` |
-
-## Body Parameters
-
-| Field | Type | Required | Values |
-| --- | --- | --- | --- |
-| `product.sku` | string | yes | `"TEA-003"` |
-| `product.name` | string | yes | `"Jasmine"` |
-| `product.category` | string | yes | `"tea"` |
-| `product.price_cents` | integer | yes | `1400` |
-
-## Example Request
-
-```json
-{
-  "product": {
-    "sku": "TEA-003",
-    "name": "Jasmine",
-    "category": "tea",
-    "price_cents": 1400
-  }
-}
-```
-
-## cURL
-
-```bash
-curl --request POST \
-  --url "http://localhost:3000/api/v1/admin/products" \
-  --header "X-Api-Key: {{api_key}}" \
-  --header "Content-Type: application/json" \
-  --header "Accept: application/json" \
-  --data '{
-  "product": {
-    "sku": "TEA-003",
-    "name": "Jasmine",
-    "category": "tea",
-    "price_cents": 1400
-  }
-}'
-```
-
-## Responses
-
-### 201 Created
-
-#### Fields
-
-| Field | Type | Required | Values |
-| --- | --- | --- | --- |
-| `id` | integer | yes | `5` |
-| `cost_cents` | integer | yes | `0` |
-| `tags` | array | yes | - |
-| `sku` | string | yes | `"TEA-003"` |
-| `name` | string | yes | `"Jasmine"` |
-| `category` | string | yes | `"tea"` |
-| `price_cents` | integer | yes | `1400` |
-
-```json
-{
-  "id": 5,
-  "cost_cents": 0,
-  "tags": [],
-  "sku": "TEA-003",
-  "name": "Jasmine",
-  "category": "tea",
-  "price_cents": 1400
-}
-```
-
-### 409 Conflict
-
-#### Fields
-
-| Field | Type | Required | Values |
-| --- | --- | --- | --- |
-| `error` | string | yes | `"sku TEA-001 already exists"` |
-
-```json
-{
-  "error": "sku TEA-001 already exists"
-}
-```
-
-### 422 Unprocessable Content
-
-#### Fields
-
-| Field | Type | Required | Values |
-| --- | --- | --- | --- |
-| `errors.sku[]` | string | yes | `"can't be blank"` |
-
-```json
-{
-  "errors": {
-    "sku": [
-      "can't be blank"
-    ]
-  }
-}
-```
-
----
-
-Resource: [Products](index.md)

data/examples/complex-test-app/docs/api/api/v1/admin/products/destroy.md

@@ -1,51 +0,0 @@
-# Delete Product
-
-`DELETE /api/v1/admin/products/:id`
-
-Namespace: `api/v1/admin`
-
-## Headers
-
-| Header | Value |
-| --- | --- |
-| X-Api-Key | `{{api_key}}` |
-| Accept | `application/json` |
-
-## Path Parameters
-
-| Field | Type | Required | Values |
-| --- | --- | --- | --- |
-| `id` | string | yes | `"4"` |
-
-## cURL
-
-```bash
-curl --request DELETE \
-  --url "http://localhost:3000/api/v1/admin/products/4" \
-  --header "X-Api-Key: {{api_key}}" \
-  --header "Accept: application/json"
-```
-
-## Responses
-
-### 204 No Content
-
-_No response body._
-
-### 404 Not Found
-
-#### Fields
-
-| Field | Type | Required | Values |
-| --- | --- | --- | --- |
-| `error` | string | yes | `"Not Found"` |
-
-```json
-{
-  "error": "Not Found"
-}
-```
-
----
-
-Resource: [Products](index.md)

data/examples/complex-test-app/docs/api/api/v1/admin/products/index.md

@@ -1,11 +0,0 @@
-# Products
-
-Namespace: `api/v1/admin`
-
-API version: `v1`
-
-| Method | Path | Description |
-| --- | --- | --- |
-| `GET` | [`/api/v1/admin/products`](list.md) | List Products |
-| `POST` | [`/api/v1/admin/products`](create.md) | Create Product |
-| `DELETE` | [`/api/v1/admin/products/:id`](destroy.md) | Delete Product |