Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

add deprecation support to defendpoint dox-gen (#66053)

bryane1e8d5323458
diff --git a/docs/api.json b/docs/api.json
index 9aba288fb05..0afd4490a80 100644
--- a/docs/api.json
+++ b/docs/api.json
@@ -9704,6 +9704,7 @@
"description" : "Server error response"
}
},
+ "deprecated" : true,
"tags" : [ "/api/activity" ]
}
},
@@ -13109,6 +13110,7 @@
"description" : "Server error response"
}
},
+ "deprecated" : true,
"tags" : [ "/api/dashboard" ]
},
"post" : {
diff --git a/src/metabase/api/macros/defendpoint/open_api.clj b/src/metabase/api/macros/defendpoint/open_api.clj
index 08414aedc11..559e3d43392 100644
--- a/src/metabase/api/macros/defendpoint/open_api.clj
+++ b/src/metabase/api/macros/defendpoint/open_api.clj
@@ -175,14 +175,16 @@
(get-in form [:params :body :schema]))
mjs-collect-definitions
fix-json-schema)
- response-schema (:response-schema form)]
+ response-schema (:response-schema form)
+ deprecated? (get-in form [:metadata :deprecated])]
;; summary is the string in the sidebar of Scalar
(cond-> {:summary (str (u/upper-case-en (name method)) " " full-path)
:description (some-> (:docstr form) str)
:parameters params
:responses default-response-schema}
body-schema (assoc :requestBody {:content {ctype {:schema body-schema}}})
- response-schema (update :responses merge (schema->response-obj response-schema))))
+ response-schema (update :responses merge (schema->response-obj response-schema))
+ deprecated? (assoc :deprecated true)))
(catch Throwable e
(throw (ex-info (str (format "Error creating OpenAPI spec for endpoint %s %s: %s"
(:method form)
diff --git a/src/metabase/api/open_api.clj b/src/metabase/api/open_api.clj
index 55686f2cec6..df5514b0a9e 100644
--- a/src/metabase/api/open_api.clj
+++ b/src/metabase/api/open_api.clj
@@ -293,6 +293,7 @@
[:parameters [:sequential ::parameter]]
[:requestBody {:optional true} ::path-item.request-body]
[:tags {:optional true} [:sequential :string]]
+ [:deprecated {:optional true} :boolean]
[:responses ::path-item.responses]])
(mr/def ::components
diff --git a/test/metabase/api/macros/defendpoint/open_api_test.clj b/test/metabase/api/macros/defendpoint/open_api_test.clj
index dde660c2d1a..6e359774368 100644
--- a/test/metabase/api/macros/defendpoint/open_api_test.clj
+++ b/test/metabase/api/macros/defendpoint/open_api_test.clj
@@ -63,3 +63,38 @@
(#'defendpoint.open-api/mjs-collect-definitions [:map [:value ::lib.schema.common/non-blank-string]])))
(is (= [{"metabase.lib.schema.common.non-blank-string" {:type :string, :minLength 1}}]
@@#'defendpoint.open-api/*definitions*))))
+
+(deftest ^:parallel deprecated-endpoint-test
+ (testing "Deprecated metadata is included in OpenAPI spec"
+ (binding [defendpoint.open-api/*definitions* (atom (sorted-map))]
+ (let [form {:method :get
+ :route {:path "/test"}
+ :docstr "A deprecated endpoint."
+ :metadata {:deprecated "0.57.0"}
+ :params {}
+ :body []}
+ result (#'defendpoint.open-api/path-item "/api/test" form)]
+ (is (true? (:deprecated result)))
+ (is (= "GET /api/test" (:summary result))))))
+
+ (testing "Non-deprecated endpoints do not have deprecated field"
+ (binding [defendpoint.open-api/*definitions* (atom (sorted-map))]
+ (let [form {:method :get
+ :route {:path "/test"}
+ :docstr "A normal endpoint."
+ :params {}
+ :body []}
+ result (#'defendpoint.open-api/path-item "/api/test" form)]
+ (is (nil? (:deprecated result)))
+ (is (= "A normal endpoint." (:description result))))))
+
+ (testing "Deprecated with multipart metadata"
+ (binding [defendpoint.open-api/*definitions* (atom (sorted-map))]
+ (let [form {:method :post
+ :route {:path "/upload"}
+ :docstr "A deprecated upload endpoint."
+ :metadata {:deprecated true :multipart true}
+ :params {}
+ :body []}
+ result (#'defendpoint.open-api/path-item "/api/upload" form)]
+ (is (true? (:deprecated result)))))))
diff --git a/test/metabase/api/macros_test.clj b/test/metabase/api/macros_test.clj
index a46d9ff9dd7..08788871e92 100644
--- a/test/metabase/api/macros_test.clj
+++ b/test/metabase/api/macros_test.clj
@@ -95,3 +95,42 @@
[{:keys [id]} :- RouteParams]
(neat))
{:route {:path "/move/:id", :regexes {:id #"[abc]{4}"}}}))
+
+(deftest ^:parallel parse-args-metadata-test
+ (testing "metadata map is parsed correctly"
+ (are [args expected] (= expected
+ (#'api.macros/parse-args args))
+ '(:get "/test"
+ "A test endpoint."
+ {:deprecated "0.57.0"}
+ []
+ (test))
+ '{:method :get
+ :route {:path "/test"}
+ :docstr "A test endpoint."
+ :metadata {:deprecated "0.57.0"}
+ :params {}
+ :body [(test)]}
+
+ '(:get "/test"
+ {:multipart true}
+ []
+ (test))
+ '{:method :get
+ :route {:path "/test"}
+ :metadata {:multipart true}
+ :params {}
+ :body [(test)]}
+
+ '(:post "/test"
+ "Deprecated endpoint."
+ {:deprecated "0.50.0", :multipart true}
+ [_route-params
+ _query-params]
+ (test))
+ '{:method :post
+ :route {:path "/test"}
+ :docstr "Deprecated endpoint."
+ :metadata {:deprecated "0.50.0", :multipart true}
+ :params {:route {:binding _route-params}, :query {:binding _query-params}}
+ :body [(test)]})))