From 07eab923f05e283b49f12b78f4735db039daaeeb Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Tue, 12 Jul 2022 20:44:29 +0200 Subject: [PATCH] :sparkles: Improve doc endpoint Add changes, added and deprecation notices --- backend/resources/api-doc-entry.tmpl | 54 +++++++++++++++++ backend/resources/api-doc.css | 36 ++++++++++- backend/resources/api-doc.tmpl | 77 +++--------------------- backend/src/app/http/doc.clj | 8 ++- backend/src/app/rpc/commands/auth.clj | 24 ++++++-- backend/src/app/rpc/commands/binfile.clj | 3 + backend/src/app/rpc/commands/demo.clj | 9 ++- backend/src/app/rpc/commands/ldap.clj | 7 ++- backend/src/app/util/services.clj | 2 +- 9 files changed, 139 insertions(+), 81 deletions(-) create mode 100644 backend/resources/api-doc-entry.tmpl diff --git a/backend/resources/api-doc-entry.tmpl b/backend/resources/api-doc-entry.tmpl new file mode 100644 index 000000000..97ce8a507 --- /dev/null +++ b/backend/resources/api-doc-entry.tmpl @@ -0,0 +1,54 @@ +
  • +
    + {#
    {{item.type}}
    #} +
    {{item.module}}:
    +
    {{item.name}}
    +
    + {% if item.deprecated %} + + Deprecated: + since v{{item.deprecated}}, + + {% endif %} + + Auth: + {% if item.auth %}YES{% else %}NO{% endif %} + +
    +
    + +
    • diff --git a/backend/resources/api-doc.css b/backend/resources/api-doc.css index 2404aea93..b7b4ad5f1 100644 --- a/backend/resources/api-doc.css +++ b/backend/resources/api-doc.css @@ -53,7 +53,7 @@ header { .rpc-item { /* border: 1px solid red; */ - cursor: pointer; + /* cursor: pointer; */ display: flex; flex-direction: column; } @@ -109,3 +109,37 @@ header { padding: 5px 10px; 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; +} diff --git a/backend/resources/api-doc.tmpl b/backend/resources/api-doc.tmpl index fa1a6d9ab..c7c447b4d 100644 --- a/backend/resources/api-doc.tmpl +++ b/backend/resources/api-doc.tmpl @@ -5,7 +5,10 @@ Builtin API Documentation - Penpot - + + + + @@ -16,92 +19,28 @@
    -

    Penpot API Documentation

    +

    Penpot API Documentation (v{{version}})

    RPC COMMAND METHODS:

      {% for item in command-methods %} -
    • -
      - {#
      {{item.type}}
      #} -
      {{item.module}}:
      -
      {{item.name}}
      -
      - - Auth: - {% if item.auth %}YES{% else %}NO{% endif %} - -
      -
      - -
      • + {% include "api-doc-entry.tmpl" with item=item %} {% endfor %}

    RPC QUERY METHODS:

      {% for item in query-methods %} -
    • -
      - {#
      {{item.type}}
      #} - -
      {{item.module}}:
      -
      {{item.name}}
      -
      - - Auth: - {% if item.auth %}YES{% else %}NO{% endif %} - -
      -
      - -
      • + {% include "api-doc-entry.tmpl" with item=item %} {% endfor %}

    RPC MUTATION METHODS:

      {% for item in mutation-methods %} -
    • -
      - {#
      {{item.type}}
      #} -
      {{item.module}}:
      -
      {{item.name}}
      -
      - - Auth: - {% if item.auth %}YES{% else %}NO{% endif %} - -
      -
      - -
      • + {% include "api-doc-entry.tmpl" with item=item %} {% endfor %}
    diff --git a/backend/src/app/http/doc.clj b/backend/src/app/http/doc.clj index c467e8644..07cd5b82e 100644 --- a/backend/src/app/http/doc.clj +++ b/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))) diff --git a/backend/src/app/rpc/commands/auth.clj b/backend/src/app/rpc/commands/auth.clj index 8d1a3bb18..74c56cc80 100644 --- a/backend/src/app/rpc/commands/auth.clj +++ b/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)) diff --git a/backend/src/app/rpc/commands/binfile.clj b/backend/src/app/rpc/commands/binfile.clj index 94a335131..d888980d9 100644 --- a/backend/src/app/rpc/commands/binfile.clj +++ b/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) diff --git a/backend/src/app/rpc/commands/demo.clj b/backend/src/app/rpc/commands/demo.clj index 3ec8f37ae..b24b00430 100644 --- a/backend/src/app/rpc/commands/demo.clj +++ b/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) diff --git a/backend/src/app/rpc/commands/ldap.clj b/backend/src/app/rpc/commands/ldap.clj index d5012058e..e1fe396e1 100644 --- a/backend/src/app/rpc/commands/ldap.clj +++ b/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 diff --git a/backend/src/app/util/services.clj b/backend/src/app/util/services.clj index 5131f45c4..642cf27af 100644 --- a/backend/src/app/util/services.clj +++ b/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))