✨ Improve doc endpoint

Add changes, added and deprecation notices

backend/src/app/http/doc.clj

@@ -35,10 +35,14 @@
                :name (d/name name)
                :module (-> (:ns mdata) (str/split ".") last)
                :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))}))]
 
-    {:command-methods
+    {:version (:main cf/version)
+     :command-methods
      (->> (:commands methods)
           (map (partial gen-doc :command))
           (sort-by (juxt :module :name)))

backend/src/app/rpc/commands/auth.clj

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

backend/src/app/rpc/commands/binfile.clj

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

backend/src/app/rpc/commands/demo.clj

@@ -11,6 +11,7 @@
    [app.common.uuid :as uuid]
    [app.config :as cf]
    [app.db :as db]
+   [app.http.doc :as doc]
    [app.loggers.audit :as audit]
    [app.rpc.commands.auth :as cmd.auth]
    [app.util.services :as sv]
@@ -21,7 +22,13 @@
 
 (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} _]
   (let [id       (uuid/next)
         sem      (System/currentTimeMillis)

backend/src/app/rpc/commands/ldap.clj

@@ -10,6 +10,7 @@
    [app.common.exceptions :as ex]
    [app.common.spec :as us]
    [app.db :as db]
+   [app.http.doc :as doc]
    [app.loggers.audit :as-alias audit]
    [app.rpc.commands.auth :as cmd.auth]
    [app.rpc.queries.profile :as profile]
@@ -28,7 +29,11 @@
   (s/keys :req-un [::email ::password]
           :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]
   (when-not ldap
     (ex/raise :type :restriction

backend/src/app/util/services.clj

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