Documentation page

docs/api.xml

@@ -10,6 +10,8 @@
       Written in a deprecated format due to it's verbosity and
       easy porting to OpenAPI's Swagger, which supports nice
       frontends.
+
+      View it at /dev/api
   -->
   <resources xmlns:xlink="http://www.w3.org/1999/xlink"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -34,7 +36,8 @@
                  name="title"
                  style="plain"
                  type="xsd:string">
-            <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
+            <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                      xml:lang="EN">
               <para>The posts title. :emojis: will be parsed as well. Plaintext. No markdown.</para>
             </wadl:doc>
           </param>
@@ -78,8 +81,9 @@
           </representation>
         </response>
         <response status="400">
-          <representation mediaType="application/xml" element="csapi:badRequest"/>
+          <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-          <representation mediaType="application/json"/>
+            <para>Not found</para>
+          </wadl:doc>
         </response> 
       </method>
     </resource>
@@ -98,8 +102,8 @@
         <request>
           <param required="true"
                  name="username"
-                 style="plain"
+                 style="url"
-                 type="xsd:url">
+                 type="xsd:string">
             <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
               <para>User URL</para>
             </wadl:doc>
@@ -157,7 +161,7 @@
                  style="plain"
                  type="xsd:url">
             <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
-              <para>Fullname of the parent (this isn't actually real, right?)</para>
+              <para>ID of the parent post. Starts with <code>p_</code> for a parent submission, and <code>c_</code> for a comment submission. Anything else will emit a 400.</para>
             </wadl:doc>
           </param>
           <param required="true"
@@ -176,8 +180,25 @@
               <para>Your messages content</para>
             </wadl:doc>
           </param>
+          <param required="true"
+                 name="submission"
+                 style="plain"
+                 type="xsd:string">
+            <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
+              <para>Parent submission (the id, right?)</para>
+            </wadl:doc>
+          </param>
+          <param required="true"
+                 name="over_18"
+                 style="plain"
+                 type="xsd:boolean">
+            <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
+              <para>If this post is marked as sensitive.</para>
+            </wadl:doc>
+          </param>
           <!-- TODO a fuck ton more -->
         </request>
+        <!-- SUCCESS -->
         <response status="200">
           <param required="false"
                  name="body"
@@ -197,15 +218,24 @@
             </wadl:doc>
           </representation>
         </response>
+        <!-- ERRORS -->
         <response status="400">
           <representation mediaType="application/xml" element="csapi:badRequest"/>
           <representation mediaType="application/json"/>
+        </response>
+        <response status="403">
+          <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
+            <para>User is exiled from the hole, or needs extra permissions.</para>
+            <para>User is banned and needs to do better.</para>
+          </wadl:doc>
+          <representation mediaType="application/xml" element="csapi:badRequest"/>
+          <representation mediaType="application/json"/>
         </response> 
       </method>
     </resource>
     
     <!-- ################################################## -->
 
-    <!-- Yada yada yada, yawn, put more here! -->
+    
   </resources>
 </wadl:application>

files/routes/__init__.py

@@ -20,6 +20,7 @@ from files.routes.jinja2 import *
 from .admin import *
 from .comments import *
 from .errors import *
+from .docs import *
 from .reporting import *
 from .front import *
 from .login import *

files/routes/comments.py

@@ -79,6 +79,7 @@ def post_pid_comment_cid(cid, pid=None, anything=None, v=None, sub=None):
 		else: template = "submission.html"
 		return render_template(template, v=v, p=post, sort=sort, comment_info=comment_info, render_replies=True, sub=post.subr)
 
+#- API
 @app.post("/comment")
 @limiter.limit("1/second;20/minute;200/hour;1000/day")
 @auth_required
@@ -91,7 +92,7 @@ def comment(v):
 	id = parent_fullname[2:]
 	parent_comment_id = None
 	rts = False
-	
+
 	if parent_fullname.startswith("p_"):
 		parent = get_post(id, v=v)
 		parent_post = parent

files/routes/docs.py

@@ -0,0 +1,35 @@
+import os
+from collections import Counter
+from json import loads
+from shutil import copyfile
+import xml
+
+import gevent
+
+from files.classes import *
+from files.helpers.actions import *
+from files.helpers.alerts import *
+from files.helpers.cloudflare import purge_files_in_cache
+from files.helpers.const import *
+from files.helpers.get import *
+from files.helpers.marsify import marsify
+from files.helpers.media import *
+from files.helpers.owoify import owoify
+from files.helpers.regex import *
+from files.helpers.sanitize import filter_emojis_only
+from files.helpers.slots import *
+from files.helpers.treasure import *
+from files.routes.front import comment_idlist
+from files.routes.routehelpers import execute_shadowban_viewers_and_voters
+from files.routes.wrappers import *
+from files.__main__ import app, cache, limiter
+
+import xml.etree.ElementTree as ET
+
+tree = ET.parse('docs/api.xml')
+
+@app.get("/dev/api")
+def get_docs_page():
+    root = tree.getroot()
+
+    return render_template("docs.html", root=tree.getroot())

files/templates/docs.html

@@ -0,0 +1,81 @@
+{% extends "default.html" %}
+
+{#% Some macros %#}
+{% macro docbook_read(info) -%}
+    {% for p in info -%}
+        {#% Lazy hack, not """conforming""" to docbook %#}
+        <p>
+            {{- p.text -}}
+        </p>
+    {%- endfor %}
+{%- endmacro %}
+
+{%- macro param_table(info) -%}
+    <table>
+        <tr>
+            <th>Param</th>
+            <th>Description</th>
+            <th>Type</th>
+            <th>Format</th>
+            <th>Required</th>
+        </tr>
+        {% for param in info %}
+
+            <tr>
+                <td><b>{{ param.attrib.name }}</b></td>
+                <td>{{- docbook_read(param[0]) -}}</td>
+                <td><i>{{ param.attrib.type }}</i></td>
+                <td>{{ param.attrib.style }}</td>
+                <td>{{ param.attrib.required }}</td>
+            </tr>
+        {% endfor %}
+    </table>
+{%- endmacro -%}
+
+{% block pagetitle %}Documentation{% endblock %}
+{% block content %}
+    <div id="docs-page">
+        <h1>rDrama REST Api Documentaion</h1>
+
+        <p><em class="text-warning">Warning: This documentation is SHIT, so get
+            used to it</em></p>
+
+        <p>You're probably here because you want to create your own application
+            which calls our REST api. Some of the stuff you see here might seem
+            ugly (it is), but it's mainly inherited from the old Ruqqus API.</p>
+
+        <p><em class="text-info">This documentation is generated from an XML WADL file.</em></p>
+
+        <hr>
+
+        {% for res in root[0] %}
+            <div class="doc-snippet">
+                {#% There's usually only one method, but this is more correct %#}
+                {% for method in res %}
+                    <h1 class="docs-path">
+                        <span class="docs-request">
+                            {{- method.attrib.name -}}
+                        </span>
+                        {{ res.attrib.path }}
+                    </h1>
+                    {% for info in method %}
+                        {% if info.tag == "{http://wadl.dev.java.net/2009/02}doc" %}
+                            {{ docbook_read(info) }}
+                        {% elif info.tag == "{http://wadl.dev.java.net/2009/02}request" %}
+                            {{ param_table(info) }}
+                        {% elif info.tag == "{http://wadl.dev.java.net/2009/02}response" %}
+                            <h4>Response <span class="docs-response">{{ info.attrib.status }}</span></h4>
+                            {% for response_child in info %}
+                                {% if response_child.tag == "{http://wadl.dev.java.net/2009/02}param" %}
+                                    {{ param_table(info) }}
+                                {% elif response_child.tag == "{http://wadl.dev.java.net/2009/02}doc" %}
+                                    {{ docbook_read(response_child) }}
+                                {% endif %}
+                            {% endfor %}
+                        {% endif %}
+                    {% endfor %}
+                {% endfor %}
+            </div>
+        {% endfor %}
+    </div>
+{% endblock %}