From ed1230d1cfb5bb28ecb2922344bc587ed9d12bd5 Mon Sep 17 00:00:00 2001
From: Joel Kaasinen <joel.kaasinen@metosin.fi>
Date: Tue, 16 May 2023 17:02:06 +0300
Subject: [PATCH 1/2] doc: openapi.md: annotating schemas

---
 doc/ring/openapi.md | 47 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/ring/openapi.md b/doc/ring/openapi.md
index 0f7103ea..76197d56 100644
--- a/doc/ring/openapi.md
+++ b/doc/ring/openapi.md
@@ -34,6 +34,53 @@ Coercion keys also contribute to the docs:
 
 Use `:request` parameter coercion (instead of `:body`) to unlock per-content-type coercions. See [Coercion](coercion.md).
 
+## Annotating schemas
+
+You can use malli properties, schema-tools data or spec-tools data to
+annotate your models with examples, descriptions and defaults that
+show up in the OpenAPI spec.
+
+Malli:
+
+```clj
+["/plus"
+ {:post
+  {:parameters
+   {:body [:map
+           [:x
+            {:title "X parameter"
+             :description "Description for X parameter"
+             :json-schema/default 42}
+            int?]
+           [:y int?]]}}}]
+```
+
+Schema:
+
+```clj
+["/plus"
+ {:post
+  {:parameters
+   {:body {:x (schema-tools.core/schema s/Num {:description "Description for X parameter"
+                                               :openapi/example 13
+                                               :openapi/default 42})
+           :y int?}}}}]
+```
+
+Spec:
+
+```clj
+["/plus"
+ {:post
+  {:parameters
+   {:body (spec-tools.data-spec/spec ::foo
+                                     {:x (schema-tools.core/spec {:spec int?
+                                                                  :description "Description for X parameter"
+                                                                  :openapi/example 13
+                                                                  :openapi/default 42})
+                                      :y int?}}}}}]
+```
+
 ## Custom OpenAPI data
 
 The `:openapi` route data key can be used to add top-level or

From 88d7caf01367acc3f8d6da21ff62d6542c9278d1 Mon Sep 17 00:00:00 2001
From: Joel Kaasinen <joel.kaasinen@metosin.fi>
Date: Tue, 16 May 2023 17:02:25 +0300
Subject: [PATCH 2/2] doc: use alpha ring-swagger-ui in ring-spec-swagger

to support openapi 3
---
 examples/ring-spec-swagger/project.clj | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/examples/ring-spec-swagger/project.clj b/examples/ring-spec-swagger/project.clj
index b24e081b..eda7bbbe 100644
--- a/examples/ring-spec-swagger/project.clj
+++ b/examples/ring-spec-swagger/project.clj
@@ -2,6 +2,7 @@
   :description "Reitit Ring App with Swagger"
   :dependencies [[org.clojure/clojure "1.10.0"]
                  [ring/ring-jetty-adapter "1.7.1"]
-                 [metosin/reitit "0.7.0-alpha3"]]
+                 [metosin/reitit "0.7.0-alpha3"]
+                 [metosin/ring-swagger-ui "5.0.0-alpha.0"]]
   :repl-options {:init-ns example.server}
   :profiles {:dev {:dependencies [[ring/ring-mock "0.3.2"]]}})