From e3962b90037b08293bcd717161a4a62f87547ae1 Mon Sep 17 00:00:00 2001 From: GV <95759575+gmsvalente@users.noreply.github.com> Date: Fri, 1 Dec 2023 08:00:49 -0300 Subject: [PATCH] Feature/swagger toplevel description (#268) * Add info to swagger config Co-authored-by: Iain Wood * Fix get info from config Co-authored-by: Iain Wood * Update documentation for descriptions Co-authored-by: Iain Wood * Fix kibit error Co-authored-by: Iain Wood --------- Co-authored-by: Iain Wood --- doc/swagger.org | 29 +++++++++++++++++------------ src/xiana/swagger.clj | 6 +++--- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/doc/swagger.org b/doc/swagger.org index 1b6e1667..a25a00c6 100644 --- a/doc/swagger.org +++ b/doc/swagger.org @@ -4,14 +4,19 @@ You need to specify your swagger.json and swagger-ui endpoints at the config file #+begin_src clojure :xiana/swagger {:uri-path "/swagger/swagger.json" - :path :swagger.json - :data {:coercion (reitit.coercion.malli/create - {:error-keys #{:coercion :in :schema :value :errors :humanized} - :compile malli.util/closed-schema - :strip-extra-keys true - :default-values true - :options nil}) - :middleware [reitit.swagger/swagger-feature]}} + :path :swagger.json + :data {:coercion (reitit.coercion.malli/create + {:error-keys #{:coercion :in :schema :value :errors :humanized} + :compile malli.util/closed-schema + :strip-extra-keys true + :default-values true + :options nil}) + :middleware [reitit.swagger/swagger-feature] + ;;; This is toplevel info for your project swagger-ui page + :info {:title "Your Project Title goes HERE" + :description "Some description" + :version "0.1"}}} + :xiana/swagger-ui {:uri-path "/swagger/swagger-ui"} #+end_src @@ -36,7 +41,7 @@ the *routes/reset* If you want a description for your endpoint on the *swagger-ui* page, include it in your route in the map associated with the swagger key as below: #+begin_src clojure - ["/users" {:get {:swagger {:description "User get endpoint"} + ["/users" {:get {:description "This is the description that will appear on swagger-ui under this endpoint" :action #'users/get-all-users}}] #+end_src @@ -49,11 +54,11 @@ you already have a malli schema for your endpoint, you can reuse that. At the moment *xiana.swagger* will ONLY work with malli schemas! #+begin_src clojure - ["/users" {:post {:action #'users/add-users :schema UsersAddReqPayload :parameters {:body UsersAddReqPayload} - :swagger {:description "User post endpoint"}}}] + :description "This is the description that will appear on swagger-ui under this endpoint"}}] + #+end_src If you don't already use a schema you can specify it inline like this: @@ -63,5 +68,5 @@ If you don't already use a schema you can specify it inline like this: :parameters {:body [:map {:closed true} [:name string?] [:age int?]]} - :swagger {:description "User post endpoint"}}}] + :description "This is the description that will appear on swagger-ui under this endpoint"}}] #+end_src diff --git a/src/xiana/swagger.clj b/src/xiana/swagger.clj index 45266dd8..182e2ee2 100644 --- a/src/xiana/swagger.clj +++ b/src/xiana/swagger.clj @@ -55,8 +55,7 @@ (if (get acc method) (if (get-in acc [method :handler]) acc - (-> acc - (assoc-in [method :handler] identity))) + (assoc-in acc [method :handler] identity)) acc)) opt-map all-methods)) @@ -118,7 +117,8 @@ [routes & {route-opt-map :route-opt-map}] (let [router (ring/router routes (or route-opt-map {})) swagger {:swagger "2.0" - :x-id ::default} + :x-id ::default + :info (get-in route-opt-map [:data :info])} map-in-order #(->> % (apply concat) (apply array-map)) paths (->> router (r/compiled-routes)