From 8a205002a81fe3dbed13e96934f522d63e81f8bb Mon Sep 17 00:00:00 2001
From: Juho Teperi <juho.teperi@iki.fi>
Date: Thu, 11 Mar 2021 20:55:52 +0200
Subject: [PATCH] Add examples for Swagger parameter description

---
 .../ring-malli-swagger/src/example/server.clj    | 16 ++++++++++++++--
 .../ring-spec-swagger/src/example/server.clj     |  8 +++++++-
 examples/ring-swagger/src/example/server.clj     | 13 +++++++++----
 3 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/examples/ring-malli-swagger/src/example/server.clj b/examples/ring-malli-swagger/src/example/server.clj
index 1a5d7d89..bc9c3861 100644
--- a/examples/ring-malli-swagger/src/example/server.clj
+++ b/examples/ring-malli-swagger/src/example/server.clj
@@ -56,13 +56,25 @@
 
         ["/plus"
          {:get {:summary "plus with malli query parameters"
-                :parameters {:query [:map [:x int?] [:y int?]]}
+                :parameters {:query [:map
+                                     [:x
+                                      {:title "X parameter"
+                                       :description "Description for X parameter"
+                                       :json-schema/default 42}
+                                      int?]
+                                     [:y int?]]}
                 :responses {200 {:body [:map [:total int?]]}}
                 :handler (fn [{{{:keys [x y]} :query} :parameters}]
                            {:status 200
                             :body {:total (+ x y)}})}
           :post {:summary "plus with malli body parameters"
-                 :parameters {:body [:map [:x int?] [:y int?]]}
+                 :parameters {:body [:map
+                                     [:x
+                                      {:title "X parameter"
+                                       :description "Description for X parameter"
+                                       :json-schema/default 42}
+                                      int?]
+                                     [:y int?]]}
                  :responses {200 {:body [:map [:total int?]]}}
                  :handler (fn [{{{:keys [x y]} :body} :parameters}]
                             {:status 200
diff --git a/examples/ring-spec-swagger/src/example/server.clj b/examples/ring-spec-swagger/src/example/server.clj
index 69615800..2337792b 100644
--- a/examples/ring-spec-swagger/src/example/server.clj
+++ b/examples/ring-spec-swagger/src/example/server.clj
@@ -13,6 +13,7 @@
             ; [reitit.ring.middleware.dev :as dev]
             ; [reitit.ring.spec :as spec]
             ; [spec-tools.spell :as spell]
+            [spec-tools.data-spec :as ds]
             [ring.adapter.jetty :as jetty]
             [muuntaja.core :as m]
             [clojure.spec.alpha :as s]
@@ -25,7 +26,12 @@
 (s/def ::size int?)
 (s/def ::file-response (s/keys :req-un [::name ::size]))
 
-(s/def ::x int?)
+;; Use data-specs to provide extra JSON-Schema properties:
+;; https://github.com/metosin/spec-tools/blob/master/docs/04_json_schema.md#annotated-specs
+(s/def ::x (ds/spec {:spec int?
+                     :name "X parameter"
+                     :description "Description for X parameter"
+                     :json-schema/default 42}))
 (s/def ::y int?)
 (s/def ::total int?)
 (s/def ::math-request (s/keys :req-un [::x ::y]))
diff --git a/examples/ring-swagger/src/example/server.clj b/examples/ring-swagger/src/example/server.clj
index 8416c2b4..bab482ca 100644
--- a/examples/ring-swagger/src/example/server.clj
+++ b/examples/ring-swagger/src/example/server.clj
@@ -11,8 +11,7 @@
             [reitit.ring.middleware.parameters :as parameters]
             ;; Uncomment to use
             ; [reitit.ring.middleware.dev :as dev]
-            ; [reitit.ring.spec :as spec]
-            ; [spec-tools.spell :as spell]
+            [schema-tools.core :as st]
             [ring.adapter.jetty :as jetty]
             [muuntaja.core :as m]
             [clojure.java.io :as io]))
@@ -53,13 +52,19 @@
 
         ["/plus"
          {:get {:summary "plus with spec query parameters"
-                :parameters {:query {:x int?, :y int?}}
+                :parameters {:query {:x (st/schema int? {:title "X parameter"
+                                                         :description "Description for X parameter"
+                                                         :json-schema/default 42})
+                                     :y int?}}
                 :responses {200 {:body {:total int?}}}
                 :handler (fn [{{{:keys [x y]} :query} :parameters}]
                            {:status 200
                             :body {:total (+ x y)}})}
           :post {:summary "plus with spec body parameters"
-                 :parameters {:body {:x int?, :y int?}}
+                 :parameters {:body {:x int? #_(st/schema int? {:name "X parameter"
+                                                         :description "Description for X parameter"
+                                                         :json-schema/default 42})
+                                     :y int?}}
                  :responses {200 {:body {:total int?}}}
                  :handler (fn [{{{:keys [x y]} :body} :parameters}]
                             {:status 200