Documentation page

2022-11-25 15:36:29 -05:00 · 2022-11-25 15:36:29 -05:00 · 7e78292827
parent ab7e5e5524
commit 7e78292827
5 changed files with 156 additions and 8 deletions
--- a/docs/api.xml
+++ b/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"/>
-          <representation mediaType="application/json"/>
+          <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
+            <para>Not found</para>
+          </wadl:doc>
        </response> 
      </method>
    </resource>
@ -98,8 +102,8 @@
        <request>
          <param required="true"
                 name="username"
-                 style="plain"
-                 type="xsd:url">
+                 style="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>
--- a/files/routes/init.py
+++ b/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 *
--- a/files/routes/comments.py
+++ b/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
--- a/files/routes/docs.py
+++ b/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())
--- a/files/templates/docs.html
+++ b/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 %}