From b776732805937ca05c57c3cfe884da0ebdfad13b Mon Sep 17 00:00:00 2001
From: Valentin Deniaud <vdeniaud@entrouvert.com>
Date: Mon, 6 Apr 2020 16:06:20 +0200
Subject: [PATCH 1/2] utils: allow specifying endpoint parameters manually
 (#41386)

---
 passerelle/utils/api.py | 54 ++++++++++++++++++++---------------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/passerelle/utils/api.py b/passerelle/utils/api.py
index 4e658145..43763a6e 100644
--- a/passerelle/utils/api.py
+++ b/passerelle/utils/api.py
@@ -43,7 +43,8 @@ class endpoint(object):
                  parameters=None,
                  cache_duration=None,
                  post=None,
-                 show=True):
+                 show=True,
+                 show_undocumented_params=True):
         self.perm = perm
         self.methods = methods
         self.serializer_type = serializer_type
@@ -61,7 +62,7 @@ class endpoint(object):
             'patch': long_description_patch or long_description,
         }
         self.example_pattern = example_pattern
-        self.parameters = parameters
+        self.parameters = parameters or {}
         self.cache_duration = cache_duration
         self.post = post
         if post:
@@ -71,6 +72,7 @@ class endpoint(object):
             if post.get('long_description'):
                 self.long_descriptions['post'] = post.get('long_description')
         self.show = show
+        self.show_undocumented_params = show_undocumented_params
 
     def __call__(self, func):
         func.endpoint_info = self
@@ -160,35 +162,33 @@ class endpoint(object):
                 return 'float'
 
         params = []
-        defaults = dict(zip(
-            reversed(inspect.getargspec(self.func).args),
-            reversed(inspect.getargspec(self.func).defaults or [])))
-        for param in inspect.getargspec(self.func).args[2:]:
-            if param == 'post_data':
-                continue
+        available_params = self.parameters
+        spec = inspect.getargspec(self.func)
+        defaults = dict(zip(reversed(spec.args), reversed(spec.defaults or [])))
+        if self.show_undocumented_params:
+            available_params = {arg: {} for arg in spec.args[2:]
+                                if arg != 'post_data' and not arg in self.parameters}
+            available_params.update(self.parameters)
+        for param, info in available_params.items():
             param_info = {'name': param}
-            if self.parameters and param in self.parameters:
-                info = self.parameters[param]
-                if info.get('description'):
-                    param_info['description'] = info['description']
-                if 'type' in info:
-                    typ = info['type']
-                    if typ == 'int':
-                        param_info['type'] = 'integer'
-                    elif typ == 'bool':
-                        param_info['type'] = 'boolean'
-                    else:
-                        param_info['type'] = typ
-                elif 'example_value' in info:
-                    typ = type_to_str(info['example_value'])
-                    if typ:
-                        param_info['type'] = typ
+            if info.get('description'):
+                param_info['description'] = info['description']
+            typ = None
+            if 'type' in info:
+                typ = info['type']
+                if typ == 'int':
+                    typ = 'integer'
+                elif typ == 'bool':
+                    typ = 'boolean'
+            elif 'example_value' in info:
+                typ = type_to_str(info['example_value'])
             if param in defaults:
                 param_info['optional'] = True
                 param_info['default_value'] = defaults[param]
-                if 'type' not in param_info:
+                if not typ:
                     typ = type_to_str(defaults[param])
-                    if typ:
-                        param_info['type'] = typ
+            if typ:
+                param_info['type'] = typ
             params.append(param_info)
+        params.sort(key=lambda x: (x.get('optional', False), x['name']))
         return params
-- 
2.20.1