reqcord 0.1.0 → 0.1.1

data/examples/spec-app/app.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+# A tiny Rails API, in one file, so the example stays readable. In a real
+# application this is just your app; Reqcord does not care how it is built.
+#
+# The same three resources as test-app — customers, users, tasks — so the two
+# examples can be compared endpoint for endpoint.
+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 ExampleApp < 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 Api
+  module V1
+    class CustomersController < ActionController::API
+      CUSTOMERS = [
+        { id: 1, name: "John Doe", email: "john@example.com" },
+        { id: 2, name: "Jane Roe", email: "jane@example.com" }
+      ].freeze
+
+      before_action :authenticate!
+
+      def index
+        render json: CUSTOMERS.first(params.fetch(:per_page, 25).to_i)
+      end
+
+      def show
+        customer = CUSTOMERS.find { |record| record[:id] == params[:id].to_i }
+
+        return render(json: { error: "Not Found" }, status: :not_found) unless customer
+
+        render json: customer
+      end
+
+      STATUSES = %w[active passive].freeze
+
+      def create
+        if params.dig(:customer, :email).to_s.empty?
+          return render(
+            json: { errors: { email: ["can't be blank"] } },
+            status: :unprocessable_entity
+          )
+        end
+
+        unless STATUSES.include?(params.dig(:customer, :status).to_s)
+          return render(
+            json: { errors: { status: ["is not included in the list"] } },
+            status: :unprocessable_entity
+          )
+        end
+
+        render json: { id: 3, **customer_params }, status: :created
+      end
+
+      private
+
+      def authenticate!
+        return if request.headers["Authorization"].present?
+
+        render json: { error: "Unauthorized" }, status: :unauthorized
+      end
+
+      def customer_params
+        params.require(:customer).permit(:name, :email, :status).to_h.symbolize_keys
+      end
+    end
+
+    class UsersController < ActionController::API
+      USERS = [
+        { id: 1, name: "John Doe", email: "john@example.com" },
+        { id: 2, name: "Jane Roe", email: "jane@example.com" }
+      ].freeze
+
+      before_action :authenticate!
+
+      def index
+        render json: USERS.first(params.fetch(:per_page, 25).to_i)
+      end
+
+      def show
+        user = USERS.find { |record| record[:id] == params[:id].to_i }
+
+        return render(json: { error: "Not Found" }, status: :not_found) unless user
+
+        render json: user
+      end
+
+      STATUSES = %w[active inactive].freeze
+
+      def create
+        if params.dig(:user, :email).to_s.empty?
+          return render(
+            json: { errors: { email: ["can't be blank"] } },
+            status: :unprocessable_entity
+          )
+        end
+
+        unless STATUSES.include?(params.dig(:user, :status).to_s)
+          return render(
+            json: { errors: { status: ["is not included in the list"] } },
+            status: :unprocessable_entity
+          )
+        end
+
+        render json: { id: 3, **user_params }, status: :created
+      end
+
+      private
+
+      def authenticate!
+        return if request.headers["Authorization"].present?
+
+        render json: { error: "Unauthorized" }, status: :unauthorized
+      end
+
+      def user_params
+        params.require(:user).permit(:name, :email, :status).to_h.symbolize_keys
+      end
+    end
+
+    class TasksController < ActionController::API
+      TASKS = [
+        { id: 1, title: "Write the docs", status: "open", priority: "high" },
+        { id: 2, title: "Ship 0.1.1", status: "done", priority: "high" },
+        { id: 3, title: "Tidy the backlog", status: "open", priority: "low" }
+      ].freeze
+
+      STATUSES = %w[open done].freeze
+      PRIORITIES = %w[low high].freeze
+
+      def index
+        tasks = TASKS
+        tasks = tasks.select { |task| task[:status] == params[:status] } if params[:status].present?
+
+        render json: tasks
+      end
+
+      before_action :find_task, only: %i[show update complete destroy]
+
+      def show
+        render json: @task
+      end
+
+      def create
+        if params.dig(:task, :title).to_s.empty?
+          return render(json: { errors: { title: ["can't be blank"] } }, status: :unprocessable_entity)
+        end
+
+        unless PRIORITIES.include?(params.dig(:task, :priority).to_s)
+          return render(json: { errors: { priority: ["is not included in the list"] } }, status: :unprocessable_entity)
+        end
+
+        render json: { id: 4, status: "open", **task_params }, status: :created
+      end
+
+      def update
+        render json: @task.merge(task_params)
+      end
+
+      def complete
+        render json: @task.merge(status: "done")
+      end
+
+      def destroy
+        head :no_content
+      end
+
+      private
+
+      # Rendering in a before_action halts the chain, so the action never runs.
+      def find_task
+        @task = TASKS.find { |task| task[:id] == params[:id].to_i }
+
+        render(json: { error: "Not Found" }, status: :not_found) unless @task
+      end
+
+      def task_params
+        params.require(:task).permit(:title, :priority, :status).to_h.symbolize_keys
+      end
+    end
+  end
+end
+
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :customers, only: %i[index show create]
+      resources :users, only: %i[index show create]
+      resources :tasks, except: %i[new edit] do
+        post :complete, on: :member
+      end
+    end
+  end
+end

data/examples/spec-app/docs/api/README.md

@@ -0,0 +1,45 @@
+# 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}}` |
+
+## Customers
+
+Namespace: `api/v1`
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | [`/api/v1/customers`](api/v1/customers/list.md) | List Customers |
+| `POST` | [`/api/v1/customers`](api/v1/customers/create.md) | Create Customer |
+| `GET` | [`/api/v1/customers/:id`](api/v1/customers/show.md) | Get Customer |
+
+## Tasks
+
+Namespace: `api/v1`
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | [`/api/v1/tasks`](api/v1/tasks/list.md) | List Tasks |
+| `POST` | [`/api/v1/tasks`](api/v1/tasks/create.md) | Create Task |
+| `DELETE` | [`/api/v1/tasks/:id`](api/v1/tasks/destroy.md) | Delete Task |
+| `GET` | [`/api/v1/tasks/:id`](api/v1/tasks/show.md) | Get Task |
+| `PATCH` | [`/api/v1/tasks/:id`](api/v1/tasks/update.md) | Update Task |
+| `POST` | [`/api/v1/tasks/:id/complete`](api/v1/tasks/complete.md) | Complete Task |
+
+## Users
+
+Namespace: `api/v1`
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | [`/api/v1/users`](api/v1/users/list.md) | List Users |
+| `POST` | [`/api/v1/users`](api/v1/users/create.md) | Create User |
+| `GET` | [`/api/v1/users/:id`](api/v1/users/show.md) | Get User |

data/examples/spec-app/docs/api/api/v1/customers/create.md

@@ -0,0 +1,95 @@
+# Create Customer
+
+`POST /api/v1/customers`
+
+Namespace: `api/v1`
+
+## Headers
+
+| Header | Value |
+| --- | --- |
+| Authorization | `Bearer {{token}}` |
+| Content-Type | `application/json` |
+| Accept | `application/json` |
+
+## Body Parameters
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `customer.name` | string | yes | `"Ada Lovelace"` |
+| `customer.email` | string | yes | `"ada@example.com"` |
+| `customer.status` | string | yes | `"active"` \| `"passive"` |
+
+## Example Request
+
+```json
+{
+  "customer": {
+    "name": "Ada Lovelace",
+    "email": "ada@example.com",
+    "status": "active"
+  }
+}
+```
+
+## cURL
+
+```bash
+curl --request POST \
+  --url "http://localhost:3000/api/v1/customers" \
+  --header "Authorization: Bearer {{token}}" \
+  --header "Content-Type: application/json" \
+  --header "Accept: application/json" \
+  --data '{
+  "customer": {
+    "name": "Ada Lovelace",
+    "email": "ada@example.com",
+    "status": "active"
+  }
+}'
+```
+
+## Responses
+
+### 201 Created
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `id` | integer | yes | `3` |
+| `name` | string | yes | `"Ada Lovelace"` |
+| `email` | string | yes | `"ada@example.com"` |
+| `status` | string | yes | `"active"` \| `"passive"` |
+
+```json
+{
+  "id": 3,
+  "name": "Ada Lovelace",
+  "email": "ada@example.com",
+  "status": "active"
+}
+```
+
+### 422 Unprocessable Content
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `errors.status[]` | string | no | `"is not included in the list"` |
+| `errors.email[]` | string | no | `"can't be blank"` |
+
+```json
+{
+  "errors": {
+    "status": [
+      "is not included in the list"
+    ]
+  }
+}
+```
+
+---
+
+Resource: [Customers](index.md)

data/examples/spec-app/docs/api/api/v1/customers/index.md

@@ -0,0 +1,11 @@
+# Customers
+
+Namespace: `api/v1`
+
+API version: `v1`
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | [`/api/v1/customers`](list.md) | List Customers |
+| `POST` | [`/api/v1/customers`](create.md) | Create Customer |
+| `GET` | [`/api/v1/customers/:id`](show.md) | Get Customer |

data/examples/spec-app/docs/api/api/v1/customers/list.md

@@ -0,0 +1,67 @@
+# List Customers
+
+`GET /api/v1/customers`
+
+Namespace: `api/v1`
+
+## Headers
+
+| Header | Value |
+| --- | --- |
+| Authorization | `Bearer {{token}}` |
+| Accept | `application/json` |
+
+## Query Parameters
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `per_page` | integer | yes | `1` |
+
+## cURL
+
+```bash
+curl --request GET \
+  --url "http://localhost:3000/api/v1/customers?per_page=1" \
+  --header "Authorization: Bearer {{token}}" \
+  --header "Accept: application/json"
+```
+
+## Responses
+
+### 200 OK
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `[].id` | integer | yes | `1` |
+| `[].name` | string | yes | `"John Doe"` |
+| `[].email` | string | yes | `"john@example.com"` |
+
+```json
+[
+  {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+]
+```
+
+### 401 Unauthorized
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `error` | string | yes | `"Unauthorized"` |
+
+```json
+{
+  "error": "Unauthorized"
+}
+```
+
+---
+
+Resource: [Customers](index.md)

data/examples/spec-app/docs/api/api/v1/customers/show.md

@@ -0,0 +1,65 @@
+# Get Customer
+
+`GET /api/v1/customers/:id`
+
+Namespace: `api/v1`
+
+## Headers
+
+| Header | Value |
+| --- | --- |
+| Authorization | `Bearer {{token}}` |
+| Accept | `application/json` |
+
+## Path Parameters
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `id` | string | yes | `"1"` |
+
+## cURL
+
+```bash
+curl --request GET \
+  --url "http://localhost:3000/api/v1/customers/1" \
+  --header "Authorization: Bearer {{token}}" \
+  --header "Accept: application/json"
+```
+
+## Responses
+
+### 200 OK
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `id` | integer | yes | `1` |
+| `name` | string | yes | `"John Doe"` |
+| `email` | string | yes | `"john@example.com"` |
+
+```json
+{
+  "id": 1,
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+```
+
+### 404 Not Found
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `error` | string | yes | `"Not Found"` |
+
+```json
+{
+  "error": "Not Found"
+}
+```
+
+---
+
+Resource: [Customers](index.md)

data/examples/spec-app/docs/api/api/v1/tasks/complete.md

@@ -0,0 +1,51 @@
+# Complete Task
+
+`POST /api/v1/tasks/:id/complete`
+
+Namespace: `api/v1`
+
+## Headers
+
+| Header | Value |
+| --- | --- |
+| Accept | `application/json` |
+
+## Path Parameters
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `id` | string | yes | `"1"` |
+
+## cURL
+
+```bash
+curl --request POST \
+  --url "http://localhost:3000/api/v1/tasks/1/complete" \
+  --header "Accept: application/json"
+```
+
+## Responses
+
+### 200 OK
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `id` | integer | yes | `1` |
+| `title` | string | yes | `"Write the docs"` |
+| `status` | string | yes | `"done"` |
+| `priority` | string | yes | `"high"` |
+
+```json
+{
+  "id": 1,
+  "title": "Write the docs",
+  "status": "done",
+  "priority": "high"
+}
+```
+
+---
+
+Resource: [Tasks](index.md)

data/examples/spec-app/docs/api/api/v1/tasks/create.md

@@ -0,0 +1,90 @@
+# Create Task
+
+`POST /api/v1/tasks`
+
+Namespace: `api/v1`
+
+## Headers
+
+| Header | Value |
+| --- | --- |
+| Content-Type | `application/json` |
+| Accept | `application/json` |
+
+## Body Parameters
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `task.title` | string | yes | `"Review the release"` |
+| `task.priority` | string | yes | `"high"` \| `"low"` |
+
+## Example Request
+
+```json
+{
+  "task": {
+    "title": "Review the release",
+    "priority": "high"
+  }
+}
+```
+
+## cURL
+
+```bash
+curl --request POST \
+  --url "http://localhost:3000/api/v1/tasks" \
+  --header "Content-Type: application/json" \
+  --header "Accept: application/json" \
+  --data '{
+  "task": {
+    "title": "Review the release",
+    "priority": "high"
+  }
+}'
+```
+
+## Responses
+
+### 201 Created
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `id` | integer | yes | `4` |
+| `status` | string | yes | `"open"` |
+| `title` | string | yes | `"Review the release"` |
+| `priority` | string | yes | `"high"` \| `"low"` |
+
+```json
+{
+  "id": 4,
+  "status": "open",
+  "title": "Review the release",
+  "priority": "high"
+}
+```
+
+### 422 Unprocessable Content
+
+#### Fields
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `errors.title[]` | string | no | `"can't be blank"` |
+| `errors.priority[]` | string | no | `"is not included in the list"` |
+
+```json
+{
+  "errors": {
+    "title": [
+      "can't be blank"
+    ]
+  }
+}
+```
+
+---
+
+Resource: [Tasks](index.md)

data/examples/spec-app/docs/api/api/v1/tasks/destroy.md

@@ -0,0 +1,35 @@
+# Delete Task
+
+`DELETE /api/v1/tasks/:id`
+
+Namespace: `api/v1`
+
+## Headers
+
+| Header | Value |
+| --- | --- |
+| Accept | `application/json` |
+
+## Path Parameters
+
+| Field | Type | Required | Values |
+| --- | --- | --- | --- |
+| `id` | string | yes | `"3"` |
+
+## cURL
+
+```bash
+curl --request DELETE \
+  --url "http://localhost:3000/api/v1/tasks/3" \
+  --header "Accept: application/json"
+```
+
+## Responses
+
+### 204 No Content
+
+_No response body._
+
+---
+
+Resource: [Tasks](index.md)

data/examples/spec-app/docs/api/api/v1/tasks/index.md

@@ -0,0 +1,14 @@
+# Tasks
+
+Namespace: `api/v1`
+
+API version: `v1`
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | [`/api/v1/tasks`](list.md) | List Tasks |
+| `POST` | [`/api/v1/tasks`](create.md) | Create Task |
+| `DELETE` | [`/api/v1/tasks/:id`](destroy.md) | Delete Task |
+| `GET` | [`/api/v1/tasks/:id`](show.md) | Get Task |
+| `PATCH` | [`/api/v1/tasks/:id`](update.md) | Update Task |
+| `POST` | [`/api/v1/tasks/:id/complete`](complete.md) | Complete Task |