Add missing swagger for https://github.com/we-promise/sure/pull/501 (#707)

spec/requests/api/v1/imports_spec.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'API V1 Imports', 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(:oauth_application) do
+    Doorkeeper::Application.create!(
+      name: 'API Docs',
+      redirect_uri: 'https://example.com/callback',
+      scopes: 'read read_write'
+    )
+  end
+
+  let(:access_token) do
+    Doorkeeper::AccessToken.create!(
+      application: oauth_application,
+      resource_owner_id: user.id,
+      scopes: 'read_write',
+      expires_in: 2.hours,
+      token: SecureRandom.hex(32)
+    )
+  end
+
+  let(:Authorization) { "Bearer #{access_token.token}" }
+
+  let(:account) do
+    Account.create!(
+      family: family,
+      name: 'Test Checking',
+      balance: 1000,
+      currency: 'USD',
+      accountable: Depository.new
+    )
+  end
+
+  let!(:pending_import) do
+    family.imports.create!(
+      type: 'TransactionImport',
+      status: 'pending',
+      account: account,
+      raw_file_str: "date,amount,name\n01/01/2024,10.00,Test Transaction"
+    )
+  end
+
+  let!(:complete_import) do
+    family.imports.create!(
+      type: 'TransactionImport',
+      status: 'complete',
+      account: account,
+      raw_file_str: "date,amount,name\n01/02/2024,20.00,Another Transaction"
+    )
+  end
+
+  path '/api/v1/imports' do
+    get 'List imports' do
+      description 'List all imports for the user\'s family with pagination and filtering.'
+      tags 'Imports'
+      security [ { bearerAuth: [] } ]
+      produces 'application/json'
+      parameter name: :Authorization, in: :header, required: true, schema: { type: :string },
+                description: 'Bearer token with read scope'
+      parameter name: :page, in: :query, type: :integer, required: false,
+                description: 'Page number (default: 1)'
+      parameter name: :per_page, in: :query, type: :integer, required: false,
+                description: 'Items per page (default: 25, max: 100)'
+      parameter name: :status, in: :query, required: false,
+                description: 'Filter by status',
+                schema: { type: :string, enum: %w[pending complete importing reverting revert_failed failed] }
+      parameter name: :type, in: :query, required: false,
+                description: 'Filter by import type',
+                schema: { type: :string, enum: %w[TransactionImport TradeImport AccountImport MintImport CategoryImport RuleImport] }
+
+      response '200', 'imports listed' do
+        schema '$ref' => '#/components/schemas/ImportCollection'
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          expect(payload.fetch('data')).to be_present
+          expect(payload.fetch('meta')).to include('current_page', 'total_count', 'total_pages', 'per_page')
+        end
+      end
+
+      response '200', 'imports filtered by status' do
+        schema '$ref' => '#/components/schemas/ImportCollection'
+
+        let(:status) { 'pending' }
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          payload.fetch('data').each do |import|
+            expect(import.fetch('status')).to eq('pending')
+          end
+        end
+      end
+
+      response '200', 'imports filtered by type' do
+        schema '$ref' => '#/components/schemas/ImportCollection'
+
+        let(:type) { 'TransactionImport' }
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          payload.fetch('data').each do |import|
+            expect(import.fetch('type')).to eq('TransactionImport')
+          end
+        end
+      end
+    end
+
+    post 'Create import' do
+      description 'Create a new import from raw CSV content.'
+      tags 'Imports'
+      security [ { bearerAuth: [] } ]
+      consumes 'application/json'
+      produces 'application/json'
+      parameter name: :Authorization, in: :header, required: true, schema: { type: :string },
+                description: 'Bearer token with write scope'
+
+      parameter name: :body, in: :body, required: true, schema: {
+        type: :object,
+        properties: {
+          raw_file_content: {
+            type: :string,
+            description: 'The raw CSV content as a string'
+          },
+          type: {
+            type: :string,
+            enum: %w[TransactionImport TradeImport AccountImport MintImport CategoryImport RuleImport],
+            description: 'Import type (defaults to TransactionImport)'
+          },
+          account_id: {
+            type: :string,
+            format: :uuid,
+            description: 'Account ID to import into'
+          },
+          publish: {
+            type: :string,
+            description: 'Set to "true" to automatically queue for processing if configuration is valid'
+          },
+          date_col_label: {
+            type: :string,
+            description: 'Header name for the date column'
+          },
+          amount_col_label: {
+            type: :string,
+            description: 'Header name for the amount column'
+          },
+          name_col_label: {
+            type: :string,
+            description: 'Header name for the transaction name column'
+          },
+          category_col_label: {
+            type: :string,
+            description: 'Header name for the category column'
+          },
+          tags_col_label: {
+            type: :string,
+            description: 'Header name for the tags column'
+          },
+          notes_col_label: {
+            type: :string,
+            description: 'Header name for the notes column'
+          },
+          date_format: {
+            type: :string,
+            description: 'Date format pattern (e.g., "%m/%d/%Y")'
+          },
+          number_format: {
+            type: :string,
+            enum: [ '1,234.56', '1.234,56', '1 234,56', '1,234' ],
+            description: 'Number format for parsing amounts'
+          },
+          signage_convention: {
+            type: :string,
+            enum: %w[inflows_positive inflows_negative],
+            description: 'How to interpret positive/negative amounts'
+          },
+          col_sep: {
+            type: :string,
+            enum: [ ',', ';' ],
+            description: 'Column separator'
+          }
+        }
+      }
+
+      response '201', 'import created' do
+        schema '$ref' => '#/components/schemas/ImportResponse'
+
+        let(:body) do
+          {
+            raw_file_content: "date,amount,name\n01/15/2024,50.00,New Transaction",
+            type: 'TransactionImport',
+            account_id: account.id,
+            date_col_label: 'date',
+            amount_col_label: 'amount',
+            name_col_label: 'name'
+          }
+        end
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          expect(payload.dig('data', 'id')).to be_present
+          expect(payload.dig('data', 'type')).to eq('TransactionImport')
+          expect(payload.dig('data', 'status')).to eq('pending')
+        end
+      end
+
+      response '422', 'validation error - file too large' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:body) do
+          {
+            raw_file_content: 'x' * (11 * 1024 * 1024), # 11MB, exceeds MAX_CSV_SIZE
+            type: 'TransactionImport'
+          }
+        end
+
+        run_test!
+      end
+    end
+  end
+
+  path '/api/v1/imports/{id}' do
+    parameter name: :Authorization, in: :header, required: true, schema: { type: :string },
+              description: 'Bearer token with read scope'
+    parameter name: :id, in: :path, type: :string, required: true, description: 'Import ID'
+
+    get 'Retrieve an import' do
+      description 'Retrieve detailed information about a specific import, including configuration and row statistics.'
+      tags 'Imports'
+      security [ { bearerAuth: [] } ]
+      produces 'application/json'
+
+      let(:id) { pending_import.id }
+
+      response '200', 'import retrieved' do
+        schema '$ref' => '#/components/schemas/ImportResponse'
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          expect(payload.dig('data', 'id')).to eq(pending_import.id)
+          expect(payload.dig('data', 'type')).to eq('TransactionImport')
+          expect(payload.dig('data', 'configuration')).to be_present
+          expect(payload.dig('data', 'stats')).to be_present
+        end
+      end
+
+      response '404', 'import not found' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:id) { SecureRandom.uuid }
+
+        run_test!
+      end
+    end
+  end
+end

spec/swagger_helper.rb

@@ -283,6 +283,86 @@ RSpec.configure do |config|
             properties: {
               message: { type: :string }
             }
+          },
+          ImportConfiguration: {
+            type: :object,
+            properties: {
+              date_col_label: { type: :string, nullable: true },
+              amount_col_label: { type: :string, nullable: true },
+              name_col_label: { type: :string, nullable: true },
+              category_col_label: { type: :string, nullable: true },
+              tags_col_label: { type: :string, nullable: true },
+              notes_col_label: { type: :string, nullable: true },
+              account_col_label: { type: :string, nullable: true },
+              date_format: { type: :string, nullable: true },
+              number_format: { type: :string, nullable: true },
+              signage_convention: { type: :string, nullable: true }
+            }
+          },
+          ImportStats: {
+            type: :object,
+            properties: {
+              rows_count: { type: :integer, minimum: 0 },
+              valid_rows_count: { type: :integer, minimum: 0, nullable: true }
+            }
+          },
+          ImportSummary: {
+            type: :object,
+            required: %w[id type status created_at updated_at],
+            properties: {
+              id: { type: :string, format: :uuid },
+              type: { type: :string, enum: %w[TransactionImport TradeImport AccountImport MintImport CategoryImport RuleImport] },
+              status: { type: :string, enum: %w[pending complete importing reverting revert_failed failed] },
+              created_at: { type: :string, format: :'date-time' },
+              updated_at: { type: :string, format: :'date-time' },
+              account_id: { type: :string, format: :uuid, nullable: true },
+              rows_count: { type: :integer, minimum: 0 },
+              error: { type: :string, nullable: true }
+            }
+          },
+          ImportDetail: {
+            type: :object,
+            required: %w[id type status created_at updated_at],
+            properties: {
+              id: { type: :string, format: :uuid },
+              type: { type: :string, enum: %w[TransactionImport TradeImport AccountImport MintImport CategoryImport RuleImport] },
+              status: { type: :string, enum: %w[pending complete importing reverting revert_failed failed] },
+              created_at: { type: :string, format: :'date-time' },
+              updated_at: { type: :string, format: :'date-time' },
+              account_id: { type: :string, format: :uuid, nullable: true },
+              error: { type: :string, nullable: true },
+              configuration: { '$ref' => '#/components/schemas/ImportConfiguration' },
+              stats: { '$ref' => '#/components/schemas/ImportStats' }
+            }
+          },
+          ImportCollection: {
+            type: :object,
+            required: %w[data meta],
+            properties: {
+              data: {
+                type: :array,
+                items: { '$ref' => '#/components/schemas/ImportSummary' }
+              },
+              meta: {
+                type: :object,
+                required: %w[current_page total_pages total_count per_page],
+                properties: {
+                  current_page: { type: :integer, minimum: 1 },
+                  next_page: { type: :integer, nullable: true },
+                  prev_page: { type: :integer, nullable: true },
+                  total_pages: { type: :integer, minimum: 0 },
+                  total_count: { type: :integer, minimum: 0 },
+                  per_page: { type: :integer, minimum: 1 }
+                }
+              }
+            }
+          },
+          ImportResponse: {
+            type: :object,
+            required: %w[data],
+            properties: {
+              data: { '$ref' => '#/components/schemas/ImportDetail' }
+            }
           }
         }
       }