From 431242c926b9f1828ca2bd9b48598237ac6d3849 Mon Sep 17 00:00:00 2001
From: Joel Kaasinen <joel.kaasinen@metosin.fi>
Date: Thu, 28 Nov 2024 09:51:31 +0200
Subject: [PATCH] doc: openapi named schemas only produced for malli

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

diff --git a/doc/ring/openapi.md b/doc/ring/openapi.md
index ec3d2264..c8011f30 100644
--- a/doc/ring/openapi.md
+++ b/doc/ring/openapi.md
@@ -5,6 +5,7 @@
 Reitit can generate [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0)
 documentation. The feature works similarly to [Swagger documentation](swagger.md).
 
+The main example is [examples/openapi](../../examples/openapi).
 The
 [ring-malli-swagger](../../examples/ring-malli-swagger)
 and
@@ -194,3 +195,16 @@ represents query parameters.
 {:parameters {:query [:map
                       [:a {:json-schema/example 1} :int]]}}
 ```
+
+### Named schemas
+
+OpenAPI supports reusable schema objects that can be referred to with
+the `"$ref": "#/components/schemas/Foo"` json-schema syntax. This is
+useful when you have multiple endpoints that use the same schema. It
+can also make OpenAPI-based code nicer for consumers of your API.
+
+Reusable schema objects are generated for Malli `:ref`s and vars. The
+[openapi example](../../examples/openapi) showcases this.
+
+Currently (as of 0.7.2), reusable schema objects are **not** generated
+for Plumatic Schema or Spec.