add defendpoint dox (#45683)

* get-sub-props -> ->sub-props because it doesn't 'get' anything

* add defendpoint dox

* make style consistent

* respond to review comment

* fix formatting

modules/drivers/snowflake/src/metabase/driver/snowflake.clj

@@ -98,7 +98,7 @@
   Snowflake driver expects a java.security.PrivateKey instance."
   [{:keys [user password account private-key-path]
     :as   details}]
-  (let [base-details (apply dissoc details (vals (secret/get-sub-props "private-key")))]
+  (let [base-details (apply dissoc details (vals (secret/->sub-props "private-key")))]
     (cond
       password
       details

src/metabase/api/common.clj

@@ -35,6 +35,46 @@
 ;;   but it may be more instructive to look at examples in our codebase.
 ;;
 ;;  <hr />
+;;
+;; ## How does defendpoint coersion work?
+;;
+;; The `defendpoint` macro uses the `auto-coerce` function to generate a let code which binds args to their decoded
+;; values. Values are decoded by their corresponding malli schema. n.b.: Only symbols in the arg->schema map will be
+;; coerced; additional aliases (eg. after the :as key) will not automatically be coerced.
+;;
+;; The exact coersion function [[mc/decode]], and uses the [[metabase.api.common.internal/defendpoint-transformer]],
+;; and gets called with the schema, value, and transformer. see: https://github.com/metosin/malli#value-transformation
+;;
+;; ### Here's an example repl session showing how it works:
+;;
+;; <pre><code>
+;; (require '[malli.core :as mc] '[malli.error :as me] '[malli.util :as mut] '[metabase.util.malli :as mu]
+;;          '[metabase.util.malli.describe :as umd] '[malli.provider :as mp] '[malli.generator :as mg]
+;;          '[malli.transform :as mtx] '[metabase.api.common.internal :refer [defendpoint-transformer]])
+;; </code></pre>
+;;
+;; To see how a schema will be transformed, call `mc/decode` with `defendpoint-transformer`.
+;;
+;; With the `:keyword` schema:
+;;
+;; <pre><code>
+;; (mc/decode :keyword "foo/bar" defendpoint-transformer)
+;; ;; => :foo/bar
+;; </code></pre>
+;;
+;; The schemas can get quite complex, ( see: https://github.com/metosin/malli#advanced-transformations ) so it's best
+;; to test them out in the REPL to see how they'll be transformed.
+;;
+;; Example:
+;; <pre><code>
+;; (def DecodableKwInt
+;;   [:int {:decode/string (fn kw-int->int-decoder [kw-int]
+;;                           (if (int? kw-int) kw-int (parse-long (name kw-int))))}])
+;;
+;; (mc/decode DecodableKwInt :123 defendpoint-transformer)
+;; ;; => 123
+;; </code></pre>
+;; <hr />
 
 (ns metabase.api.common
   "Dynamic variables and utility functions/macros for writing API functions."

src/metabase/models/secret.clj

@@ -132,7 +132,7 @@
                           ;; that is unique
                           [(vec (:value secret)) ext?])})))
 
-(defn get-sub-props
+(defn ->sub-props
   "Return a map of secret subproperties for the property `connection-property-name`."
   [connection-property-name]
   (let [sub-prop-types [:path :value :options :id]
@@ -166,7 +166,7 @@
   {:added "0.42.0"}
   [details conn-prop-nm]
   (let [{path-kw :path, value-kw :value, options-kw :options, id-kw :id}
-        (get-sub-props conn-prop-nm)
+        (->sub-props conn-prop-nm)
         value  (cond
                  ;; ssl-root-certs will need their prefix removed, and to be base 64 decoded (#20319)
                  (and (value-kw details) (#{"ssl-client-cert" "ssl-root-cert"} conn-prop-nm)
@@ -207,7 +207,7 @@
 (defn get-secret-string
   "Get the value of a secret property from the database details as a string."
   [details secret-property]
-  (let [{path-kw :path, value-kw :value, options-kw :options, id-kw :id} (get-sub-props secret-property)
+  (let [{path-kw :path, value-kw :value, options-kw :options, id-kw :id} (->sub-props secret-property)
         id (id-kw details)
         ;; When a secret is updated, we get both a new value as well as the ID of old secret.
         value (or (when-let [value (value-kw details)]