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] 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