Improve doc endpoint

Add changes, added and deprecation notices
This commit is contained in:
Andrey Antukh 2022-07-12 20:44:29 +02:00
parent 2e077e3ea9
commit 07eab923f0
9 changed files with 139 additions and 81 deletions

View file

@ -0,0 +1,54 @@
<li class="rpc-item">
<div class="rpc-row-info">
{# <div class="type">{{item.type}}</div> #}
<div class="module">{{item.module}}:</div>
<div class="name">{{item.name}}</div>
<div class="tags">
{% if item.deprecated %}
<span class="tag">
<span>Deprecated:</span>
<span>since v{{item.deprecated}}</span>,
</span>
{% endif %}
<span class="tag">
<span>Auth:</span>
<span>{% if item.auth %}YES{% else %}NO{% endif %}</span>
</span>
</div>
</div>
<div class="rpc-row-detail hidden">
<h3>DOCSTRING:</h3>
<section class="padded-section">
{% if item.added %}
<p class="small"><strong>Added:</strong> on v{{item.added}}</p>
{% endif %}
{% if item.deprecated %}
<p class="small"><strong>Deprecated:</strong> since v{{item.deprecated}}</p>
{% endif %}
{% if item.docs %}
<p class="docstring"> {{item.docs}}</p>
{% endif %}
</section>
{% if item.changes %}
<h3>CHANGES:</h3>
<section class="padded-section">
<ul class="changes">
{% for change in item.changes %}
<li><strong>{{change.0}}</strong> - {{change.1}}</li>
{% endfor %}
</ul>
</section>
{% endif %}
<h3>SPEC EXPLAIN:</h3>
<section class="padded-section">
<pre class="spec-explain">{{item.spec}}</pre>
</section>
</div>
</li>

View file

@ -53,7 +53,7 @@ header {
.rpc-item { .rpc-item {
/* border: 1px solid red; */ /* border: 1px solid red; */
cursor: pointer; /* cursor: pointer; */
display: flex; display: flex;
flex-direction: column; flex-direction: column;
} }
@ -109,3 +109,37 @@ header {
padding: 5px 10px; padding: 5px 10px;
padding-bottom: 20px; padding-bottom: 20px;
} }
.rpc-row-detail p {
font-weight: 200;
}
.rpc-row-detail p.small {
margin-top: 2px;
margin-bottom: 2px;
font-size: 10px;
}
.rpc-row-detail p.small {
margin-top: 2px;
margin-bottom: 2px;
font-size: 10px;
}
.rpc-row-detail strong {
font-weight: 500;
}
.rpc-row-detail .changes {
font-weight: 200;
list-style: none;
padding: 0px;
}
.rpc-row-detail .padded-section {
padding: 0px 10px;
}
p.small strong {
font-size: 10px;
}

View file

@ -5,7 +5,10 @@
<meta name="robots" content="noindex,nofollow"> <meta name="robots" content="noindex,nofollow">
<meta http-equiv="x-ua-compatible" content="ie=edge" /> <meta http-equiv="x-ua-compatible" content="ie=edge" />
<title>Builtin API Documentation - Penpot</title> <title>Builtin API Documentation - Penpot</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@200;300;400;500;700&display=swap" rel="stylesheet">
<style> <style>
{% include "api-doc.css" %} {% include "api-doc.css" %}
</style> </style>
@ -16,92 +19,28 @@
<body> <body>
<main> <main>
<header> <header>
<h1>Penpot API Documentation</h1> <h1>Penpot API Documentation (v{{version}})</h1>
</header> </header>
<section class="rpc-doc-content"> <section class="rpc-doc-content">
<h2>RPC COMMAND METHODS:</h2> <h2>RPC COMMAND METHODS:</h2>
<ul class="rpc-items"> <ul class="rpc-items">
{% for item in command-methods %} {% for item in command-methods %}
<li class="rpc-item"> {% include "api-doc-entry.tmpl" with item=item %}
<div class="rpc-row-info">
{# <div class="type">{{item.type}}</div> #}
<div class="module">{{item.module}}:</div>
<div class="name">{{item.name}}</div>
<div class="tags">
<span class="tag">
<span>Auth:</span>
<span>{% if item.auth %}YES{% else %}NO{% endif %}</span>
</span>
</div>
</div>
<div class="rpc-row-detail hidden">
{% if item.docs %}
<h3>DOCSTRING:</h3>
<p>{{item.docs}}</p>
{% endif %}
<h3>SPEC EXPLAIN:</h3>
<pre>{{item.spec}}</pre>
</div>
</li>
{% endfor %} {% endfor %}
</ul> </ul>
<h2>RPC QUERY METHODS:</h2> <h2>RPC QUERY METHODS:</h2>
<ul class="rpc-items"> <ul class="rpc-items">
{% for item in query-methods %} {% for item in query-methods %}
<li class="rpc-item"> {% include "api-doc-entry.tmpl" with item=item %}
<div class="rpc-row-info">
{# <div class="type">{{item.type}}</div> #}
<div class="module">{{item.module}}:</div>
<div class="name">{{item.name}}</div>
<div class="tags">
<span class="tag">
<span>Auth:</span>
<span>{% if item.auth %}YES{% else %}NO{% endif %}</span>
</span>
</div>
</div>
<div class="rpc-row-detail hidden">
{% if item.docs %}
<h3>DOCSTRING:</h3>
<p>{{item.docs}}</p>
{% endif %}
<h3>SPEC EXPLAIN:</h3>
<pre>{{item.spec}}</pre>
</div>
</li>
{% endfor %} {% endfor %}
</ul> </ul>
<h2>RPC MUTATION METHODS:</h2> <h2>RPC MUTATION METHODS:</h2>
<ul class="rpc-items"> <ul class="rpc-items">
{% for item in mutation-methods %} {% for item in mutation-methods %}
<li class="rpc-item"> {% include "api-doc-entry.tmpl" with item=item %}
<div class="rpc-row-info">
{# <div class="type">{{item.type}}</div> #}
<div class="module">{{item.module}}:</div>
<div class="name">{{item.name}}</div>
<div class="tags">
<span class="tag">
<span>Auth:</span>
<span>{% if item.auth %}YES{% else %}NO{% endif %}</span>
</span>
</div>
</div>
<div class="rpc-row-detail hidden">
{% if item.docs %}
<h3>DOCSTRING:</h3>
<p>{{item.docs}}</p>
{% endif %}
<h3>SPEC EXPLAIN:</h3>
<pre>{{item.spec}}</pre>
</div>
</li>
{% endfor %} {% endfor %}
</ul> </ul>
</section> </section>

View file

@ -35,10 +35,14 @@
:name (d/name name) :name (d/name name)
:module (-> (:ns mdata) (str/split ".") last) :module (-> (:ns mdata) (str/split ".") last)
:auth (:auth mdata true) :auth (:auth mdata true)
:docs (::sv/docs mdata) :docs (::sv/docstring mdata)
:deprecated (::deprecated mdata)
:added (::added mdata)
:changes (some->> (::changes mdata) (partition-all 2) (map vec))
:spec (get-spec-str (::sv/spec mdata))}))] :spec (get-spec-str (::sv/spec mdata))}))]
{:command-methods {:version (:main cf/version)
:command-methods
(->> (:commands methods) (->> (:commands methods)
(map (partial gen-doc :command)) (map (partial gen-doc :command))
(sort-by (juxt :module :name))) (sort-by (juxt :module :name)))

View file

@ -12,6 +12,7 @@
[app.config :as cf] [app.config :as cf]
[app.db :as db] [app.db :as db]
[app.emails :as eml] [app.emails :as eml]
[app.http.doc :as-alias doc]
[app.loggers.audit :as audit] [app.loggers.audit :as audit]
[app.rpc.mutations.teams :as teams] [app.rpc.mutations.teams :as teams]
[app.rpc.queries.profile :as profile] [app.rpc.queries.profile :as profile]
@ -133,7 +134,9 @@
(sv/defmethod ::login-with-password (sv/defmethod ::login-with-password
"Performs authentication using penpot password." "Performs authentication using penpot password."
{:auth false ::rlimit/permits (cf/get :rlimit-password)} {:auth false
::rlimit/permits (cf/get :rlimit-password)
::doc/added "1.15"}
[cfg params] [cfg params]
(login-with-password cfg params)) (login-with-password cfg params))
@ -144,7 +147,8 @@
(sv/defmethod ::logout (sv/defmethod ::logout
"Clears the authentication cookie and logout the current session." "Clears the authentication cookie and logout the current session."
{:auth false} {:auth false
::doc/added "1.15"}
[{:keys [session] :as cfg} _] [{:keys [session] :as cfg} _]
(with-meta {} (with-meta {}
{:transform-response (:delete session)})) {:transform-response (:delete session)}))
@ -171,7 +175,9 @@
(s/keys :req-un [::token ::password])) (s/keys :req-un [::token ::password]))
(sv/defmethod ::recover-profile (sv/defmethod ::recover-profile
{:auth false ::rlimit/permits (cf/get :rlimit-password)} {:auth false
::rlimit/permits (cf/get :rlimit-password)
::doc/added "1.15"}
[cfg params] [cfg params]
(recover-profile cfg params)) (recover-profile cfg params))
@ -224,7 +230,9 @@
(s/keys :req-un [::email ::password] (s/keys :req-un [::email ::password]
:opt-un [::invitation-token])) :opt-un [::invitation-token]))
(sv/defmethod ::prepare-register-profile {:auth false} (sv/defmethod ::prepare-register-profile
{:auth false
::doc/added "1.15"}
[cfg params] [cfg params]
(prepare-register cfg params)) (prepare-register cfg params))
@ -355,7 +363,9 @@
(s/keys :req-un [::token ::fullname])) (s/keys :req-un [::token ::fullname]))
(sv/defmethod ::register-profile (sv/defmethod ::register-profile
{:auth false ::rlimit/permits (cf/get :rlimit-password)} {:auth false
::rlimit/permits (cf/get :rlimit-password)
::doc/added "1.15"}
[{:keys [pool] :as cfg} params] [{:keys [pool] :as cfg} params]
(db/with-atomic [conn pool] (db/with-atomic [conn pool]
(-> (assoc cfg :conn conn) (-> (assoc cfg :conn conn)
@ -409,7 +419,9 @@
(s/def ::request-profile-recovery (s/def ::request-profile-recovery
(s/keys :req-un [::email])) (s/keys :req-un [::email]))
(sv/defmethod ::request-profile-recovery {:auth false} (sv/defmethod ::request-profile-recovery
{:auth false
::doc/added "1.15"}
[cfg params] [cfg params]
(request-profile-recovery cfg params)) (request-profile-recovery cfg params))

View file

@ -15,6 +15,7 @@
[app.common.uuid :as uuid] [app.common.uuid :as uuid]
[app.config :as cf] [app.config :as cf]
[app.db :as db] [app.db :as db]
[app.http.doc :as doc]
[app.media :as media] [app.media :as media]
[app.rpc.queries.files :as files] [app.rpc.queries.files :as files]
[app.rpc.queries.projects :as projects] [app.rpc.queries.projects :as projects]
@ -808,6 +809,7 @@
(sv/defmethod ::export-binfile (sv/defmethod ::export-binfile
"Export a penpot file in a binary format." "Export a penpot file in a binary format."
{::doc/added "1.15"}
[{:keys [pool] :as cfg} {:keys [profile-id file-id include-libraries? embed-assets?] :as params}] [{:keys [pool] :as cfg} {:keys [profile-id file-id include-libraries? embed-assets?] :as params}]
(db/with-atomic [conn pool] (db/with-atomic [conn pool]
(files/check-read-permissions! conn profile-id file-id) (files/check-read-permissions! conn profile-id file-id)
@ -827,6 +829,7 @@
(sv/defmethod ::import-binfile (sv/defmethod ::import-binfile
"Import a penpot file in a binary format." "Import a penpot file in a binary format."
{::doc/added "1.15"}
[{:keys [pool] :as cfg} {:keys [profile-id project-id file] :as params}] [{:keys [pool] :as cfg} {:keys [profile-id project-id file] :as params}]
(db/with-atomic [conn pool] (db/with-atomic [conn pool]
(projects/check-read-permissions! conn profile-id project-id) (projects/check-read-permissions! conn profile-id project-id)

View file

@ -11,6 +11,7 @@
[app.common.uuid :as uuid] [app.common.uuid :as uuid]
[app.config :as cf] [app.config :as cf]
[app.db :as db] [app.db :as db]
[app.http.doc :as doc]
[app.loggers.audit :as audit] [app.loggers.audit :as audit]
[app.rpc.commands.auth :as cmd.auth] [app.rpc.commands.auth :as cmd.auth]
[app.util.services :as sv] [app.util.services :as sv]
@ -21,7 +22,13 @@
(s/def ::create-demo-profile any?) (s/def ::create-demo-profile any?)
(sv/defmethod ::create-demo-profile {:auth false} (sv/defmethod ::create-demo-profile
"A command that is responsible of creating a demo purpose
profile. It only works if the `demo-users` flag is inabled in the
configuration."
{:auth false
::doc/added "1.15"
::doc/changes ["1.15" "This methos is migrated from mutations to commands."]}
[{:keys [pool] :as cfg} _] [{:keys [pool] :as cfg} _]
(let [id (uuid/next) (let [id (uuid/next)
sem (System/currentTimeMillis) sem (System/currentTimeMillis)

View file

@ -10,6 +10,7 @@
[app.common.exceptions :as ex] [app.common.exceptions :as ex]
[app.common.spec :as us] [app.common.spec :as us]
[app.db :as db] [app.db :as db]
[app.http.doc :as doc]
[app.loggers.audit :as-alias audit] [app.loggers.audit :as-alias audit]
[app.rpc.commands.auth :as cmd.auth] [app.rpc.commands.auth :as cmd.auth]
[app.rpc.queries.profile :as profile] [app.rpc.queries.profile :as profile]
@ -28,7 +29,11 @@
(s/keys :req-un [::email ::password] (s/keys :req-un [::email ::password]
:opt-un [::invitation-token])) :opt-un [::invitation-token]))
(sv/defmethod ::login-with-ldap {:auth false} (sv/defmethod ::login-with-ldap
"Performs the authentication using LDAP backend. Only works if LDAP
is properly configured and enabled with `login-with-ldap` flag."
{:auth false
::doc/added "1.15"}
[{:keys [session tokens ldap] :as cfg} params] [{:keys [session tokens ldap] :as cfg} params]
(when-not ldap (when-not ldap
(ex/raise :type :restriction (ex/raise :type :restriction

View file

@ -27,7 +27,7 @@
(throw (IllegalArgumentException. "Missing arguments on `defmethod` macro."))) (throw (IllegalArgumentException. "Missing arguments on `defmethod` macro.")))
(let [mdata (assoc mdata (let [mdata (assoc mdata
::docs (some-> docs str/<<-) ::docstring (some-> docs str/<<-)
::spec sname ::spec sname
::name (name sname)) ::name (name sname))