From 431242c926b9f1828ca2bd9b48598237ac6d3849 Mon Sep 17 00:00:00 2001 From: Joel Kaasinen Date: Thu, 28 Nov 2024 09:51:31 +0200 Subject: [PATCH 1/3] 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. From fc132f3a928d0a78e5a852a0a0001ef5f0f1bca5 Mon Sep 17 00:00:00 2001 From: Joel Kaasinen Date: Thu, 28 Nov 2024 09:56:02 +0200 Subject: [PATCH 2/3] doc: swagger reusable schema definitions supported only for malli --- doc/ring/swagger.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/doc/ring/swagger.md b/doc/ring/swagger.md index cece1208..05b2e4a7 100644 --- a/doc/ring/swagger.md +++ b/doc/ring/swagger.md @@ -286,7 +286,17 @@ 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. + +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. + +## TOD * ClojureScript * example for [Macchiato](https://github.com/macchiato-framework) From 059f93aee817219e1b82ad24683bd74ec37e2ec7 Mon Sep 17 00:00:00 2001 From: Joel Kaasinen Date: Mon, 2 Dec 2024 07:47:36 +0200 Subject: [PATCH 3/3] doc: fix typo, mention swagger ui handling of names schemas --- doc/ring/openapi.md | 1 + doc/ring/swagger.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/ring/openapi.md b/doc/ring/openapi.md index c8011f30..7515b933 100644 --- a/doc/ring/openapi.md +++ b/doc/ring/openapi.md @@ -202,6 +202,7 @@ 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. diff --git a/doc/ring/swagger.md b/doc/ring/swagger.md index 05b2e4a7..1b1a6b8c 100644 --- a/doc/ring/swagger.md +++ b/doc/ring/swagger.md @@ -290,13 +290,14 @@ Example with: 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. +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. -## TOD +## TODO * ClojureScript * example for [Macchiato](https://github.com/macchiato-framework)