/dev/api: PATCH endpoint with JSON model support

r2/r2/controllers/api_docs.py

@@ -121,6 +121,7 @@ class ApidocsController(RedditController):
         - `extensions`: URI extensions the API method supports
         - `parameters`: Dictionary of possible parameter names and descriptions.
         - `extends`: API method from which to inherit documentation
+        - `json_model`: The JSON model used instead of normal POST parameters
         """
 
         api_docs = defaultdict(lambda: defaultdict(dict))
@@ -129,7 +130,7 @@ class ApidocsController(RedditController):
             if not action:
                 continue
 
-            valid_methods = ('GET', 'POST', 'PUT', 'DELETE')
+            valid_methods = ('GET', 'POST', 'PUT', 'DELETE', 'PATCH')
             api_doc = getattr(func, '_api_doc', None)
             if api_doc and 'section' in api_doc and method in valid_methods:
                 docs = {}

r2/r2/lib/validator/validator.py

@@ -2440,7 +2440,11 @@ class VValidatedJSON(VJSON):
         def spec_docs(self):
             spec_lines = []
             spec_lines.append('[')
-            for line in self.spec.spec_docs().split('\n'):
+            if hasattr(self.spec, 'spec_docs'):
+                array_docs = self.spec.spec_docs()
+            else:
+                array_docs = self.spec.param_docs()[self.spec.param]
+            for line in array_docs.split('\n'):
                 spec_lines.append('  ' + line)
             spec_lines[-1] += ','
             spec_lines.append('  ...')
@@ -2507,16 +2511,18 @@ class VValidatedJSON(VJSON):
         # into a global (c.errors) and then checked by @validate.
         return self.spec.run(data)
 
-    def param_docs(self):
+    def docs_model(self):
         spec_md = self.spec.spec_docs()
 
         # indent for code formatting
         spec_md = '\n'.join(
             '    ' + line for line in spec_md.split('\n')
         )
+        return spec_md
 
+    def param_docs(self):
         return {
-            self.param: 'json data:\n\n' + spec_md,
+            self.param: 'json data:\n\n' + self.docs_model(),
         }
 
 

r2/r2/templates/apihelp.html

@@ -254,8 +254,9 @@ example, `t3_15bfi0`.
               <%
                 params = docs.get('parameters')
                 base_params = extends.get('parameters') if extends else None
+                json_model = docs.get('json_model')
               %>
-              %if params or base_params:
+              %if params or base_params or json_model:
                 <table class="parameters">
                 %if params:
                   %for param in sorted(params):
@@ -275,6 +276,12 @@ example, `t3_15bfi0`.
                     %endif
                   %endfor
                 %endif
+                %if json_model:
+                  <tr class="json-model">
+                    <th>${_("This endpoint expects JSON data using this model")}</th>
+                    <td>${unsafe(safemarkdown(json_model.docs_model(), wrap=False))}</td>
+                  </tr>
+                %endif
                 </table>
               %endif
             </div>