From db14cb93d607bf02c5096aa39e6dc643a35165a2 Mon Sep 17 00:00:00 2001
From: Ad Schellevis <ad@opnsense.org>
Date: Sat, 3 May 2025 18:08:54 +0200
Subject: [PATCH] collect_api_endpoints.py: move collect_api_modules into its
 own module, for https://github.com/opnsense/docs/pull/712

---
 collect_api_endpoints.py | 22 ++--------------------
 lib/__init__.py          |  2 +-
 lib/utils.py             | 25 +++++++++++++++++++++++++
 3 files changed, 28 insertions(+), 21 deletions(-)
 create mode 100644 lib/utils.py

diff --git a/collect_api_endpoints.py b/collect_api_endpoints.py
index 2e6841c5..29c0c5c1 100755
--- a/collect_api_endpoints.py
+++ b/collect_api_endpoints.py
@@ -27,9 +27,7 @@
 import os
 import argparse
 from jinja2 import Template
-from lib import ApiParser
-
-EXCLUDE_CONTROLLERS = ['Core/Api/FirmwareController.php']
+from lib.utils import collect_api_modules
 
 
 def source_url(repo, src_filename):
@@ -46,25 +44,9 @@ if __name__ == '__main__':
     parser.add_argument('--debug', help='enable debug mode', default=False, action='store_true')
     cmd_args = parser.parse_args()
 
-    # collect all endpoints
-    all_modules = dict()
-    for root, dirs, files in os.walk(cmd_args.source):
-        for fname in sorted(files):
-            filename = os.path.join(root, fname)
-            skip = False
-            for to_exclude in EXCLUDE_CONTROLLERS:
-                if filename.endswith(to_exclude):
-                    skip = True
-                    break
-            if not skip and filename.lower().endswith('controller.php') and filename.find('mvc/app/controllers') > -1 \
-                    and root.endswith('Api'):
-                payload = ApiParser(filename, cmd_args.debug).parse_api_php()
-                if len(payload) > 0:
-                    if payload['module'] not in all_modules:
-                        all_modules[payload['module']] = list()
-                    all_modules[payload['module']].append(payload)
 
     # writeout .rst files
+    all_modules = collect_api_modules(cmd_args.source, cmd_args.debug)
     for module_name in all_modules:
         target_filename = "%s/source/development/api/%s/%s.rst" % (
             os.path.dirname(__file__), cmd_args.repo, module_name
diff --git a/lib/__init__.py b/lib/__init__.py
index f19f9b49..fe9e7fbc 100644
--- a/lib/__init__.py
+++ b/lib/__init__.py
@@ -40,7 +40,7 @@ DEFAULT_BASE_METHODS = {
 
 
 class ApiParser:
-    def __init__(self, filename, debug=False):
+    def __init__(self,filename: str,debug: bool=False):
         self._debug = debug
         self._filename = filename
         self.base_filename = os.path.basename(filename)
diff --git a/lib/utils.py b/lib/utils.py
new file mode 100644
index 00000000..1838256d
--- /dev/null
+++ b/lib/utils.py
@@ -0,0 +1,25 @@
+import os
+from . import ApiParser
+
+EXCLUDE_CONTROLLERS = ['Core/Api/FirmwareController.php']
+
+def collect_api_modules(source: str, debug: bool = False) -> dict[str, list[dict]]:
+    # collect all endpoints
+    all_modules = dict()
+    for root, dirs, files in os.walk(source):
+        for fname in sorted(files):
+            filename = os.path.join(root, fname)
+            skip = False
+            for to_exclude in EXCLUDE_CONTROLLERS:
+                if filename.endswith(to_exclude):
+                    skip = True
+                    break
+            if not skip and filename.lower().endswith('controller.php') and filename.find('mvc/app/controllers') > -1 \
+                    and root.endswith('Api'):
+                payload = ApiParser(filename, debug).parse_api_php()
+                if len(payload) > 0:
+                    if payload['module'] not in all_modules:
+                        all_modules[payload['module']] = list()
+                    all_modules[payload['module']].append(payload)
+
+    return all_modules