Merge pull request #711 from metosin/doc-named-schemas

document status of named definition support for openapi&swagger

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,17 @@ 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.
+These schemas are also rendered in their own section in Swagger UI.
+
+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.

doc/ring/swagger.md

@@ -286,7 +286,18 @@ Example with:
 ; ("/common/ping" "/one/ping" "/two/ping" "/two/deep/ping")
 ```
 
-### TODO
+## Reusable schema definitions
+
+Swagger supports having reusable schema definitions under the
+`"definitions"` key. These can be reused in different parts of
+swagger.json using the `"$ref": "#/definitions/Foo"` syntax. These
+definitions are also rendered in their own section in Swagger UI.
+
+Reusable schema objects are generated for Malli `:ref`s and vars.
+Currently (as of 0.7.2), reusable schema objects are **not** generated
+for Plumatic Schema or Spec.
+
+## TODO
 
 * ClojureScript
   * example for [Macchiato](https://github.com/macchiato-framework)