Defendpoint 2.0 (metabase#51559)

* Split Kondo lint fixes off into metabase#51747

* Merge changes from metabase#51660

* Reworked API documentation generation code

* Oops Markdown not YAML

* BIG documentation generation improvements

* Don't try to style tables ourselves

* Fix lint errors

* Fix tests 🔧

* Fix Kondo warnings

* Update OpenAPI dox generator to handle Defendpoint v2

* Update OpenAPI dox generator to handle Defendpoint v2

* Test fixes 🔧

* Fix uberjar compilation

* PR feedback from @escherize

* Deprecate the old `defendpoint`

* Nuke the old version of the API documentation code (new version will be merged in metabase#51872)

* Remove empty file

* Disable output validation in prod

* Fix the way we define defendpoint 2 handlers

Author: camsaul

.clj-kondo/config.edn

@@ -326,6 +326,7 @@
     metabase.analyze               #{metabase.analyze}
     metabase.api                   #{metabase.api.common
                                      metabase.api.dataset
+                                     metabase.api.macros
                                      metabase.api.permission-graph
                                      metabase.api.routes}                                           ; TODO -- consolidate these into a real API namespace. I think the `*current-user*` type stuff might need to be moved into a separate module.
     metabase.async                 #{metabase.async.streaming-response
@@ -888,6 +889,7 @@
    metabase.api.embed-test/with-chain-filter-fixtures!                                                                       hooks.common/let-one-with-optional-value
    metabase.api.embed-test/with-temp-card                                                                                    hooks.common/let-one-with-optional-value
    metabase.api.embed-test/with-temp-dashcard                                                                                hooks.common/let-one-with-optional-value
+   metabase.api.macros/defendpoint                                                                                           hooks.metabase.api.macros/defendpoint
    metabase.api.persist-test/with-setup!                                                                                     hooks.common/with-one-top-level-binding
    metabase.api.public-test/with-required-param-card!                                                                        hooks.common/with-one-binding
    metabase.api.public-test/with-temp-public-card                                                                            hooks.common/let-one-with-optional-value

.clj-kondo/src/hooks/metabase/api/macros.clj

@@ -0,0 +1,49 @@
+(ns hooks.metabase.api.macros
+  (:require
+   [clj-kondo.hooks-api :as api]))
+
+(defn defendpoint
+  [arg]
+  (letfn [(update-defendpoint [node]
+            (let [[defendpoint method route & more] (:children node)
+                  [result-schema & more] (if (= (api/sexpr (first more)) :-)
+                                           (drop 1 more)
+                                           (cons nil more))
+                  [_docstring & more] (if (api/string-node? (first more))
+                                        more
+                                        (cons nil more))
+                  [metadata & more] (if (api/map-node? (first more))
+                                      more
+                                      (cons nil more))
+                  [params & body] more
+                  [bindings schemas] (when (api/vector-node? params)
+                                       (loop [bindings [], schemas [], [x y & more] (:children params)]
+                                         (cond
+                                           (not x)
+                                           [bindings schemas]
+
+                                           (= (api/sexpr x) :-)
+                                           (recur bindings (conj schemas y) more)
+
+                                           :else
+                                           (recur (conj bindings x) schemas (cons y more)))))]
+              (-> (api/list-node
+                   (list
+                    (api/token-node 'do)
+                    defendpoint
+                    method
+                    route
+                    (api/list-node
+                     (list*
+                      (api/token-node 'do)
+                      (filter some? (list* metadata result-schema schemas))))
+                    (api/list-node
+                     (list*
+                      (api/token-node `let)
+                      (api/vector-node (into []
+                                             (mapcat (fn [a-binding]
+                                                       [a-binding (api/token-node nil)]))
+                                             bindings))
+                      body))))
+                  (with-meta (meta node)))))]
+    (update arg :node update-defendpoint)))

.clj-kondo/test/hooks/metabase/api/macros_test.clj

@@ -0,0 +1,35 @@
+(ns hooks.metabase.api.macros-test
+  (:require
+   [clj-kondo.hooks-api :as api]
+   [clojure.test :refer :all]
+   [hooks.metabase.api.macros]))
+
+(deftest ^:parallel defendpoint-test
+  (let [form '(api.macros/defendpoint :post "/" :- [:map [:collection_id :int]]
+                "Create a new [[Timeline]]."
+                [_route-params
+                 _query-params
+                 {:keys [icon], collection-id :collection_id, :as body} :- [:map
+                                                                            [:name    ms/NonBlankString]
+                                                                            [:default {:optional true} [:maybe :boolean]]]]
+                (body icon)
+                (body collection-id))
+        node (-> form pr-str api/parse-string)]
+    (is (= '(do
+              api.macros/defendpoint
+              :post
+              "/"
+              (do
+                [:map [:collection_id :int]]
+                [:map
+                 [:name    ms/NonBlankString]
+                 [:default {:optional true} [:maybe :boolean]]])
+              (clojure.core/let [_route-params nil
+                                 _query-params nil
+                                 {:keys [icon], collection-id :collection_id, :as body} nil]
+                (body icon)
+                (body collection-id)))
+           (-> {:node node}
+               hooks.metabase.api.macros/defendpoint
+               :node
+               api/sexpr)))))

.github/file-paths.yaml

@@ -79,7 +79,6 @@ backend_specs: &backend_specs
   - "test_modules/**"
   - "modules/drivers/*/test/**"
   - "test_config/**"
-  - "dev/**"
   - "test_resources/**"
 
 backend_all: &backend_all

enterprise/backend/src/metabase_enterprise/advanced_config/api/logs.clj

@@ -32,6 +32,7 @@
                                          (date-part :month month)]})]
     results))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint GET "/query_execution/:yyyy-mm"
   "Fetch rows for the month specified by `:yyyy-mm` from the query_execution logs table.
   Must be a superuser."

enterprise/backend/src/metabase_enterprise/advanced_permissions/api/application.clj

@@ -11,6 +11,7 @@
 
 (set! *warn-on-reflection* true)
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint GET "/graph"
   "Fetch a graph of Application Permissions."
   []
@@ -34,6 +35,7 @@
   [graph]
   (update graph :groups dejsonify-groups))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint PUT "/graph"
   "Do a batch update of Application Permissions by passing a modified graph."
   [:as {body :body

enterprise/backend/src/metabase_enterprise/advanced_permissions/api/impersonation.clj

@@ -5,6 +5,7 @@
    [metabase.util.malli.schema :as ms]
    [toucan2.core :as t2]))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint GET "/"
   "Fetch a list of all Impersonation policies currently in effect, or a single policy if both `group_id` and `db_id`
   are provided."
@@ -16,6 +17,7 @@
     (t2/select-one :model/ConnectionImpersonation :group_id group_id :db_id db_id)
     (t2/select :model/ConnectionImpersonation {:order-by [[:id :asc]]})))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint DELETE "/:id"
   "Delete a Connection Impersonation entry."
   [id]

enterprise/backend/src/metabase_enterprise/audit_app/api/user.clj

@@ -11,6 +11,7 @@
    [metabase.util.malli.schema :as ms]
    [toucan2.core :as t2]))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint GET "/audit-info"
   "Gets audit info for the current user if he has permissions to access the audit collection.
   Otherwise return an empty map."
@@ -26,6 +27,7 @@
        {(u/slugify (:name question-overview)) (:id question-overview)
         (u/slugify (:name dashboard-overview)) (:id dashboard-overview)}))))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint DELETE "/:id/subscriptions"
   "Delete all Alert and DashboardSubscription subscriptions for a User (i.e., so they will no longer receive them).
   Archive all Alerts and DashboardSubscriptions created by the User. Only allowed for admins or for the current user."

enterprise/backend/src/metabase_enterprise/billing/billing.clj

@@ -53,6 +53,7 @@
                {:name "Token expiration date" :value (valid-thru) :format "string" :display "value"}
                {:name "Plan" :value "Enterprise Airgap" :format "string" :display "value"}]}))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint GET "/"
   "Get billing information. This acts as a proxy between `metabase-billing-info-url` and the client,
    using the embedding token and signed in user's email to fetch the billing information."

…rise/content_verification/api/review.clj …t_verification/api/moderation_review.cljenterprise/backend/src/metabase_enterprise/content_verification/api/review.clj renamed to enterprise/backend/src/metabase_enterprise/content_verification/api/moderation_review.clj enterprise/backend/src/metabase_enterprise/content_verification/api/review.clj renamed to enterprise/backend/src/metabase_enterprise/content_verification/api/moderation_review.clj

@@ -1,4 +1,5 @@
-(ns metabase-enterprise.content-verification.api.review
+(ns metabase-enterprise.content-verification.api.moderation-review
+  "`api/ee/moderation-review` routes."
   (:require
    [compojure.core :refer [POST]]
    [metabase.api.common :as api]
@@ -7,6 +8,7 @@
    [metabase.util.malli.schema :as ms]
    [toucan2.core :as t2]))
 
+#_{:clj-kondo/ignore [:deprecated-var]}
 (api/defendpoint POST "/"
   "Create a new `ModerationReview`."
   [:as {{:keys [text moderated_item_id moderated_item_type status]} :body}]