From 34afc1f5978dd6360bb0414f7c2fc3e3398e949b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Mata?= <juanjo.mata@gmail.com>
Date: Fri, 13 Feb 2026 19:40:23 +0100
Subject: [PATCH] Document merchants API endpoints (#980)

Add rswag request specs for merchants index/show and define a MerchantDetail schema used by the docs. Update the generated OpenAPI document with merchants paths and schema.
---
 docs/api/openapi.yaml                  | 68 +++++++++++++++++++++++
 spec/requests/api/v1/merchants_spec.rb | 77 ++++++++++++++++++++++++++
 spec/swagger_helper.rb                 | 11 ++++
 3 files changed, 156 insertions(+)
 create mode 100644 spec/requests/api/v1/merchants_spec.rb

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 9417f1e97..d6fb8e2ee 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -357,6 +357,31 @@ components:
           format: uuid
         name:
           type: string
+    MerchantDetail:
+      type: object
+      required:
+      - id
+      - name
+      - type
+      - created_at
+      - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        type:
+          type: string
+          enum:
+          - FamilyMerchant
+          - ProviderMerchant
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
     Tag:
       type: object
       required:
@@ -848,6 +873,49 @@ components:
         pagination:
           "$ref": "#/components/schemas/Pagination"
 paths:
+  "/api/v1/merchants":
+    get:
+      summary: List merchants
+      tags:
+      - Merchants
+      security:
+      - apiKeyAuth: []
+      responses:
+        '200':
+          description: merchants listed
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  "$ref": "#/components/schemas/MerchantDetail"
+  "/api/v1/merchants/{id}":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Merchant ID
+      schema:
+        type: string
+    get:
+      summary: Retrieve a merchant
+      tags:
+      - Merchants
+      security:
+      - apiKeyAuth: []
+      responses:
+        '200':
+          description: merchant retrieved
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/MerchantDetail"
+        '404':
+          description: merchant not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v1/accounts":
     get:
       summary: List accounts
diff --git a/spec/requests/api/v1/merchants_spec.rb b/spec/requests/api/v1/merchants_spec.rb
new file mode 100644
index 000000000..adfed1dfd
--- /dev/null
+++ b/spec/requests/api/v1/merchants_spec.rb
@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'API V1 Merchants', type: :request do
+  let(:family) do
+    Family.create!(
+      name: 'API Family',
+      currency: 'USD',
+      locale: 'en',
+      date_format: '%m-%d-%Y'
+    )
+  end
+
+  let(:user) do
+    family.users.create!(
+      email: 'api-user@example.com',
+      password: 'password123',
+      password_confirmation: 'password123'
+    )
+  end
+
+  let(:api_key) do
+    key = ApiKey.generate_secure_key
+    ApiKey.create!(
+      user: user,
+      name: 'API Docs Key',
+      key: key,
+      scopes: %w[read_write],
+      source: 'web'
+    )
+  end
+
+  let(:'X-Api-Key') { api_key.plain_key }
+
+  let!(:family_merchant) { family.merchants.create!(name: 'Coffee Shop') }
+
+  path '/api/v1/merchants' do
+    get 'List merchants' do
+      tags 'Merchants'
+      security [ { apiKeyAuth: [] } ]
+      produces 'application/json'
+
+      response '200', 'merchants listed' do
+        schema type: :array, items: { '$ref' => '#/components/schemas/MerchantDetail' }
+
+        run_test!
+      end
+    end
+  end
+
+  path '/api/v1/merchants/{id}' do
+    parameter name: :id, in: :path, type: :string, required: true, description: 'Merchant ID'
+
+    get 'Retrieve a merchant' do
+      tags 'Merchants'
+      security [ { apiKeyAuth: [] } ]
+      produces 'application/json'
+
+      response '200', 'merchant retrieved' do
+        schema '$ref' => '#/components/schemas/MerchantDetail'
+
+        let(:id) { family_merchant.id }
+
+        run_test!
+      end
+
+      response '404', 'merchant not found' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:id) { SecureRandom.uuid }
+
+        run_test!
+      end
+    end
+  end
+end
diff --git a/spec/swagger_helper.rb b/spec/swagger_helper.rb
index 5874fcb90..8a990075b 100644
--- a/spec/swagger_helper.rb
+++ b/spec/swagger_helper.rb
@@ -254,6 +254,17 @@ RSpec.configure do |config|
               name: { type: :string }
             }
           },
+          MerchantDetail: {
+            type: :object,
+            required: %w[id name type created_at updated_at],
+            properties: {
+              id: { type: :string, format: :uuid },
+              name: { type: :string },
+              type: { type: :string, enum: %w[FamilyMerchant ProviderMerchant] },
+              created_at: { type: :string, format: :'date-time' },
+              updated_at: { type: :string, format: :'date-time' }
+            }
+          },
           Tag: {
             type: :object,
             required: %w[id name color],