reqcord 0.1.1 → 0.1.2

data/examples/spec-app/generate.rb

@@ -1,14 +0,0 @@
-# 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/spec-app/reqcord.yml

@@ -1,27 +0,0 @@
-version: 1
-
-test:
-  framework: rspec
-  # A directory is enough: Reqcord runs `rspec <paths>`.
-  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}}"
-  body:
-    password: "{{password}}"

data/examples/spec-app/spec/requests/customers_spec.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-# Ordinary request specs. As with Minitest, nothing here mentions Reqcord.
-#
-# The status assertions are spelled out because this example runs on plain
-# rspec-core; with rspec-rails you would write `have_http_status(:created)`.
-require "spec_helper"
-
-RSpec.describe "Customers", type: :request do
-  let(:auth) { { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" } }
-
-  it "lists customers" do
-    get "/api/v1/customers", params: { per_page: 1 }, headers: auth, as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "shows customer" do
-    get "/api/v1/customers/1", headers: auth, as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "returns not found for an unknown customer" do
-    get "/api/v1/customers/999", headers: auth, as: :json
-
-    expect(response.status).to eq(404)
-  end
-
-  it "creates an active customer" do
-    post "/api/v1/customers",
-         params: { customer: { name: "Ada Lovelace", email: "ada@example.com", status: "active" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(201)
-  end
-
-  it "creates a passive customer" do
-    post "/api/v1/customers",
-         params: { customer: { name: "Grace Hopper", email: "grace@example.com", status: "passive" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(201)
-  end
-
-  it "rejects an unknown status" do
-    post "/api/v1/customers",
-         params: { customer: { name: "Ada Lovelace", email: "ada@example.com", status: "inactive" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(422)
-  end
-
-  it "rejects a customer without an email" do
-    post "/api/v1/customers",
-         params: { customer: { name: "Ada Lovelace", email: "", status: "active" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(422)
-  end
-
-  it "requires authentication" do
-    get "/api/v1/customers", as: :json
-
-    expect(response.status).to eq(401)
-  end
-end

data/examples/spec-app/spec/requests/tasks_spec.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-# Ordinary request specs. As with Minitest, nothing here mentions Reqcord.
-require "spec_helper"
-
-RSpec.describe "Tasks", type: :request do
-  it "lists tasks" do
-    get "/api/v1/tasks", as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "lists open tasks" do
-    get "/api/v1/tasks", params: { status: "open" }, as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "lists done tasks" do
-    get "/api/v1/tasks", params: { status: "done" }, as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "shows a task" do
-    get "/api/v1/tasks/1", as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "returns not found for an unknown task" do
-    get "/api/v1/tasks/999", as: :json
-
-    expect(response.status).to eq(404)
-  end
-
-  it "creates a high priority task" do
-    post "/api/v1/tasks", params: { task: { title: "Review the release", priority: "high" } }, as: :json
-
-    expect(response.status).to eq(201)
-  end
-
-  it "creates a low priority task" do
-    post "/api/v1/tasks", params: { task: { title: "Water the plants", priority: "low" } }, as: :json
-
-    expect(response.status).to eq(201)
-  end
-
-  it "rejects a task without a title" do
-    post "/api/v1/tasks", params: { task: { title: "", priority: "high" } }, as: :json
-
-    expect(response.status).to eq(422)
-  end
-
-  it "rejects an unknown priority" do
-    post "/api/v1/tasks", params: { task: { title: "Anything", priority: "urgent" } }, as: :json
-
-    expect(response.status).to eq(422)
-  end
-
-  it "updates a task" do
-    patch "/api/v1/tasks/1", params: { task: { title: "Write better docs" } }, as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "completes a task" do
-    post "/api/v1/tasks/1/complete", as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "deletes a task" do
-    delete "/api/v1/tasks/3", as: :json
-
-    expect(response.status).to eq(204)
-  end
-end

data/examples/spec-app/spec/requests/users_spec.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-# Ordinary request specs. As with Minitest, nothing here mentions Reqcord.
-require "spec_helper"
-
-RSpec.describe "Users", type: :request do
-  let(:auth) { { "Authorization" => "Bearer eyJhbGciOiJIUzI1NiJ9.super-secret" } }
-
-  it "lists users" do
-    get "/api/v1/users", params: { per_page: 1 }, headers: auth, as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "shows user" do
-    get "/api/v1/users/1", headers: auth, as: :json
-
-    expect(response.status).to eq(200)
-  end
-
-  it "returns not found for an unknown user" do
-    get "/api/v1/users/999", headers: auth, as: :json
-
-    expect(response.status).to eq(404)
-  end
-
-  it "creates an active user" do
-    post "/api/v1/users",
-         params: { user: { name: "Ada Lovelace", email: "ada@example.com", status: "active" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(201)
-  end
-
-  it "creates an inactive user" do
-    post "/api/v1/users",
-         params: { user: { name: "Grace Hopper", email: "grace@example.com", status: "inactive" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(201)
-  end
-
-  it "rejects an unknown status" do
-    post "/api/v1/users",
-         params: { user: { name: "Ada Lovelace", email: "ada@example.com", status: "passive" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(422)
-  end
-
-  it "rejects a user without an email" do
-    post "/api/v1/users",
-         params: { user: { name: "Ada Lovelace", email: "", status: "active" } },
-         headers: auth,
-         as: :json
-
-    expect(response.status).to eq(422)
-  end
-
-  it "requires authentication" do
-    get "/api/v1/users", as: :json
-
-    expect(response.status).to eq(401)
-  end
-end

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

@@ -1,17 +0,0 @@
-# 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/test-app/README.md

@@ -1,57 +0,0 @@
-# test-app (Minitest)
-
-A one file Rails API with ordinary Minitest integration tests, and the
-documentation Reqcord generates from them. Three resources, each there to
-show something different in the output:
-
-| Resource | Shows |
-| --- | --- |
-| `customers` | bearer auth, a closed set of values (`"active" \| "passive"`), 401/422 responses |
-| `users` | a second authenticated resource with its own status set |
-| `tasks` | no auth, full CRUD, `PATCH` and `PUT` folded into one page, a `204`, a member action (`complete`), a filtered index (`?status=open`) |
-
-```text
-app.rb                              the application
-test/integration/*_test.rb          ordinary integration tests
-reqcord.yml                         Reqcord configuration
-docs/api/                           generated output, committed here so you can
-                                    read it without running anything:
-  api/v1/{customers,users,tasks}/*.md Markdown, one page per endpoint
-  curl/api/v1/**/*.sh                 runnable cURL scripts
-  postman/collection.json             Postman collection (Hoppscotch imports it)
-  dataset.json                        the canonical dataset behind all three
-```
-
-## Regenerate
-
-```bash
-ruby generate.rb
-```
-
-In a real application you would run `bin/rails reqcord:generate` instead;
-`generate.rb` only exists because this example has no `bin/rails`.
-
-`reqcord.yml` only names the test directory; with no `bin/rails` around,
-Reqcord runs every `*_test.rb` beneath it itself.
-
-Filters work the same way:
-
-```bash
-RESOURCE=tasks ruby generate.rb
-RESOURCE=customers,users ruby generate.rb
-VERSION=v1 ruby generate.rb
-```
-
-## What to look at
-
-- The tests never mention Reqcord.
-- `Authorization: Bearer eyJ...` is written as `Bearer {{token}}` in
-  [docs/api/api/v1/customers/create.md](docs/api/api/v1/customers/create.md).
-- `customer.status` is documented as `"active" | "passive"`: two tests sent
-  those and passed, a third sent `"inactive"` and was rejected, so the
-  rejected value never becomes a documented parameter.
-- One endpoint carries every status its tests produced: `201`, `422`, `401`.
-- Each cURL example uses the real captured path, so it can be pasted into a
-  terminal once `{{token}}` is replaced; the same request is in
-  [docs/api/postman/collection.json](docs/api/postman/collection.json) with
-  `{{token}}` as a collection variable.

data/examples/test-app/app.rb

@@ -1,212 +0,0 @@
-# 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.
-#
-# Three resources, each showing something different in the output:
-#   customers  authenticated, a closed set of statuses ("active" | "passive")
-#   users      the same shape with its own status set, to show two resources
-#   tasks      public (no auth), full CRUD with PATCH/PUT, a 204, a member
-#              action (`complete`) and a filtered index (`?status=`)
-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/test-app/docs/api/README.md

@@ -1,45 +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}}` |
-
-## 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/test-app/docs/api/api/v1/customers/create.md

@@ -1,95 +0,0 @@
-# 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.email[]` | string | no | `"can't be blank"` |
-| `errors.status[]` | string | no | `"is not included in the list"` |
-
-```json
-{
-  "errors": {
-    "email": [
-      "can't be blank"
-    ]
-  }
-}
-```
-
----
-
-Resource: [Customers](index.md)