Feature/swagger toplevel description (#268)

* Add info to swagger config Co-authored-by: Iain Wood <iain.wood@flexiana.com> * Fix get info from config Co-authored-by: Iain Wood <iain.wood@flexiana.com> * Update documentation for descriptions Co-authored-by: Iain Wood <iain.wood@flexiana.com> * Fix kibit error Co-authored-by: Iain Wood <iain.wood@flexiana.com> --------- Co-authored-by: Iain Wood <iain.wood@flexiana.com>
Flexiana · Dec 1, 2023 · e3962b9 · e3962b9
1 parent eae5996
commit e3962b9
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 15 deletions.
diff --git 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
@@ -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)