From 7a407396ee95b67561dd4b5c181996e58e8c6984 Mon Sep 17 00:00:00 2001
From: Gustavo Valente <gustavomsvalente@gmail.com>
Date: Fri, 1 Dec 2023 07:44:08 -0300
Subject: [PATCH] Update documentation for descriptions

Co-authored-by: Iain Wood <iain.wood@flexiana.com>
---
 doc/swagger.org | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 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