From 9dea0bac654d992320177567a01730e12b873783 Mon Sep 17 00:00:00 2001
From: colin <colin@nixc.us>
Date: Wed, 23 Jul 2025 18:45:08 -0400
Subject: [PATCH] Fix API documentation to reflect actual API responses

- Removed non-existent fields: transaction_id, transaction_no
- Updated field names to match actual database schema (id instead of transaction_id)
- Added comprehensive field documentation for POST endpoint
- Updated all example responses to match actual API behavior
- Added required vs optional field documentation
- Fixed response structure to match actual API responses
---
 docker/ploughshares/templates/api_docs.html | 127 ++++++++++----------
 1 file changed, 63 insertions(+), 64 deletions(-)

diff --git a/docker/ploughshares/templates/api_docs.html b/docker/ploughshares/templates/api_docs.html
index d748a0a..c8d30c8 100644
--- a/docker/ploughshares/templates/api_docs.html
+++ b/docker/ploughshares/templates/api_docs.html
@@ -23,22 +23,14 @@
                     <h5>Response:</h5>
                     <pre class="bg-dark text-light p-2"><code>[
   {
-    "transaction_id": 1,
-    "transaction_no": "78708",
-    "transaction_type": "Subcontract",
-    "company_division": "C A E Inc",
-    "amount": 0.00,
-    "recipient": "US Army",
-    "created_at": "2023-07-02T12:34:56.789012"
-  },
-  {
-    "transaction_id": 2,
-    "transaction_no": "78709",
+    "id": 1,
     "transaction_type": "Purchase Order",
-    "company_division": "Example Corp",
-    "amount": 1000.00,
+    "company_division": "Test Corp",
+    "amount": "1000.00",
     "recipient": "Test Recipient",
-    "created_at": "2023-07-03T10:11:12.131415"
+    "description": "Test transaction",
+    "approved": false,
+    "created_at": "2025-07-23T22:43:35.520130"
   }
 ]</code></pre>
                 </div>
@@ -53,40 +45,35 @@
                     
                     <h5>Response:</h5>
                     <pre class="bg-dark text-light p-2"><code>{
-  "transaction": {
-    "transaction_id": 1,
-    "transaction_no": "78708",
-    "transaction_type": "Subcontract",
-    "company_division": "C A E Inc",
-    "address_1": "5585 Cote de Liesse",
-    "address_2": "P O Box 1800",
-    "city": "ST LAURENT",
-    "province": "QC",
-    "region": "Quebec",
-    "postal_code": "H4T 1G6",
-    "is_primary": true,
-    "source_date": "2023-08-23",
-    "source_description": "Source Description",
-    "description": "7000XR Full Flight Simulator (FFS) in Global 6000/6500 configuration (subc)",
-    "amount": 0.00,
-    "recipient": "US Army",
-    "commodity_class": "Aerospace",
-    "contract_number": "SUMMARY",
-    "comments": "Subcontract with Leidos, US, through CAE Defense & Security...",
-    "created_at": "2023-07-02T12:34:56.789012"
+  "navigation": {
+    "next_id": null,
+    "prev_id": null
   },
-  "documents": [
-    {
-      "document_id": 1,
-      "transaction_id": 1,
-      "filename": "78708_20240501.pdf",
-      "file_path": "1/78708_20240501.pdf",
-      "document_type": "Contract",
-      "description": "Contract document",
-      "note": "Original contract",
-      "upload_date": "2023-07-02T12:34:56.789012"
-    }
-  ]
+  "transaction": {
+    "id": 1,
+    "transaction_type": "Purchase Order",
+    "company_division": "Test Corp",
+    "address_1": "",
+    "address_2": "",
+    "city": "",
+    "province": "",
+    "region": "",
+    "postal_code": "",
+    "is_primary": false,
+    "source_date": null,
+    "source_description": "",
+    "grant_type": "",
+    "description": "Test transaction",
+    "amount": "1000.00",
+    "recipient": "Test Recipient",
+    "commodity_class": "",
+    "contract_number": "",
+    "comments": "",
+    "approved": false,
+    "approved_at": null,
+    "approved_by": null,
+    "created_at": "2025-07-23T22:43:35.520130"
+  }
 }</code></pre>
                 </div>
                 
@@ -98,16 +85,36 @@
                         They must be explicitly approved using the approval endpoint before being considered valid.
                     </p>
                     
+                    <h5>Required Fields:</h5>
+                    <ul>
+                        <li><code>transaction_type</code> - Type of transaction (e.g., "Purchase Order", "Subcontract")</li>
+                        <li><code>company_division</code> - Company or division name</li>
+                        <li><code>recipient</code> - Recipient of the transaction</li>
+                    </ul>
+                    
+                    <h5>Optional Fields:</h5>
+                    <ul>
+                        <li><code>amount</code> - Transaction amount (defaults to 0)</li>
+                        <li><code>description</code> - Transaction description</li>
+                        <li><code>address_1</code>, <code>address_2</code>, <code>city</code>, <code>province</code>, <code>region</code>, <code>postal_code</code> - Address fields</li>
+                        <li><code>source_date</code> - Date in YYYY-MM-DD format</li>
+                        <li><code>source_description</code> - Source description</li>
+                        <li><code>grant_type</code> - Type of grant</li>
+                        <li><code>commodity_class</code> - Commodity classification</li>
+                        <li><code>contract_number</code> - Contract number</li>
+                        <li><code>comments</code> - Additional comments</li>
+                        <li><code>is_primary</code> - Boolean flag (defaults to false)</li>
+                    </ul>
+                    
                     <h5>Complete Example:</h5>
                     <pre class="bg-dark text-light p-2"><code id="createTransaction">curl -X POST "http://{{ server_name }}/api/transaction" \
   -H "Content-Type: application/json" \
   -d '{
-    "transaction_no": "12345",
     "transaction_type": "Purchase Order",
     "company_division": "Example Corp",
-    "description": "Test transaction",
+    "recipient": "Test Recipient",
     "amount": 1000.00,
-    "recipient": "Test Recipient"
+    "description": "Test transaction"
   }'</code></pre>
                     <button class="btn btn-sm btn-secondary" onclick="copyToClipboard('createTransaction')">Copy</button>
                     
@@ -169,22 +176,14 @@
                     <h5>Response:</h5>
                     <pre class="bg-dark text-light p-2"><code>[
   {
-    "transaction_id": 1,
-    "transaction_type": "Subcontract",
-    "company_division": "C A E Inc",
-    "amount": 0.00,
-    "recipient": "US Army",
-    "created_at": "2023-07-02T12:34:56.789012",
-    "approved": false
-  },
-  {
-    "transaction_id": 2,
+    "id": 1,
     "transaction_type": "Purchase Order",
-    "company_division": "Example Corp",
-    "amount": 1000.00,
+    "company_division": "Test Corp",
+    "amount": "1000.00",
     "recipient": "Test Recipient",
-    "created_at": "2023-07-03T10:11:12.131415",
-    "approved": false
+    "description": "Test transaction",
+    "approved": false,
+    "created_at": "2025-07-23T22:43:35.520130"
   }
 ]</code></pre>
                 </div>