Merge pull request #623 from metosin/doc-openapi

doc: openapi.md: annotating schemas

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

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"]]}})