From bd1dddbaab7059597c2a016ac387f09a2047f365 Mon Sep 17 00:00:00 2001
From: Eduardo Silva <eduardo@eth0.com.br>
Date: Wed, 11 Feb 2026 17:47:34 -0300
Subject: [PATCH] Enhance API documentation: format example output and add curl
 command examples

---
 api_v2/views.py                         | 18 ++++++++++++++++++
 templates/api_v2/api_documentation.html | 11 +++++++----
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/api_v2/views.py b/api_v2/views.py
index e9234b5..4b14b2d 100644
--- a/api_v2/views.py
+++ b/api_v2/views.py
@@ -1,3 +1,4 @@
+import json
 import uuid as uuid_lib
 
 from django.contrib import messages
@@ -116,6 +117,23 @@ def view_api_docs(request):
                 doc_data = view_func.api_doc.copy()
                 doc_data['url_pattern'] = str(pattern.pattern)
                 doc_data['name'] = pattern.name
+
+                # Convert examples to curl commands
+                if 'examples' in doc_data:
+                    curl_examples = {}
+                    for key, example in doc_data['examples'].items():
+                        method = example.get('method', 'POST')
+                        body = example.get('json', {})
+                        url = f"https://your-server/api/v2/{doc_data['url_pattern']}"
+                        
+                        curl_cmd = f"curl -X {method} {url} \\\n"
+                        curl_cmd += "  -H 'token: <YOUR_API_TOKEN>' \\\n"
+                        curl_cmd += "  -H 'Content-Type: application/json' \\\n"
+                        curl_cmd += f"  -d '{json.dumps(body, indent=4)}'"
+                        
+                        curl_examples[key] = curl_cmd
+                    doc_data['examples'] = curl_examples
+
                 docs.append(doc_data)
 
     context = {
diff --git a/templates/api_v2/api_documentation.html b/templates/api_v2/api_documentation.html
index 9cbdf12..c3fbe06 100644
--- a/templates/api_v2/api_documentation.html
+++ b/templates/api_v2/api_documentation.html
@@ -67,7 +67,10 @@
                                             <td>
                                                 {{ param.description }}
                                                 {% if param.example %}
-                                                <br><small class="text-muted">{% trans 'Example' %}: {{ param.example }}</small>
+                                                <br>
+                                                    <small class="text-muted">
+                                                        {% trans 'Example' %}: {{ param.example }}
+                                                    </small>
                                                 {% endif %}
                                             </td>
                                         </tr>
@@ -112,7 +115,7 @@
                                 <div class="card bg-light mb-2">
                                     <div class="card-body p-2">
                                         <strong>{{ key }}</strong>
-                                        <pre class="mb-0"><code>{{ example|pprint }}</code></pre>
+                                        <pre class="mb-0"><code>{{ example }}</code></pre>
                                     </div>
                                 </div>
                                 {% endfor %}
@@ -128,7 +131,7 @@
 </div>
 
 <script>
-    document.addEventListener("DOMContentLoaded", function () {
+    document.addEventListener("DOMContentLoaded", function ( ) {
         // Function to toggle icon class on collapse events
         function setupIconToggle(collapseId, iconSelector) {
             $('#' + collapseId).on('show.bs.collapse', function () {
@@ -141,7 +144,7 @@
         }
 
         // Setup for all collapsible elements
-        $('.collapse').each(function () {
+        $('.collapse').each(function  () {
             var id = $(this).attr('id');
             setupIconToggle(id, '.fa-chevron-right, .fa-chevron-down');
         });