From 21b7a2cf42bd5d79fd9bfcd00dda154b55a42328 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Fri, 29 Mar 2024 15:02:07 +0100
Subject: [PATCH 1/6] Use the resolve-refs partial as soon as possible
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Call it right after accessing the site.Data,
since it is recursing it will solve all references in the tree.
That way we don't need to wonder where to call it,
we trust the validators that the refs will be used in the right place.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 layouts/partials/openapi/render-api.html        |  6 +-----
 layouts/partials/openapi/render-operation.html  |  6 ++----
 layouts/partials/openapi/render-parameters.html |  3 ---
 layouts/partials/openapi/render-request.html    | 14 +++++---------
 layouts/partials/openapi/render-responses.html  |  7 +------
 layouts/shortcodes/http-api.html                |  5 ++++-
 6 files changed, 13 insertions(+), 28 deletions(-)

diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html
index 8af18e970..fcbb1cfc7 100644
--- a/layouts/partials/openapi/render-api.html
+++ b/layouts/partials/openapi/render-api.html
@@ -5,15 +5,11 @@
   * `api_data`: the OpenAPI data
   * `base_url`: the base URL: that is, the part we glue onto the front
   of each value in `paths` to get a complete URL.
-  * `path`: the directory under /data where we found this API definition.
-  We use this to resolve "$ref" values, since they are relative to the schema's
-  location.
 
 */}}
 
 {{ $api_data := index .api_data }}
 {{ $base_url := .base_url }}
-{{ $path := .path }}
 
 {{ range $path_name, $path_data := $api_data.paths }}
 
@@ -21,7 +17,7 @@
 
     {{/* note that a `paths` entry can be a $ref */}}
 
-    {{ $params := dict "endpoint" $endpoint "path" $path }}
+    {{ $params := dict "endpoint" $endpoint }}
 
     {{ with $path_data.get }}
 
diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html
index 253e2efe8..8c6fce0e6 100644
--- a/layouts/partials/openapi/render-operation.html
+++ b/layouts/partials/openapi/render-operation.html
@@ -5,7 +5,6 @@
   * `method`: the method, e.g. GET, PUT
   * `endpoint`: the endpoint
   * `operation_data`: the OpenAPI data for the operation
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
 
   This template renders the operation as a `<section>` containing:
 
@@ -21,7 +20,6 @@
 {{ $method := .method }}
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
-{{ $path := .path }}
 {{ $anchor := anchorize $endpoint }}
 
 <section class="rendered-data http-api {{ $method }}">
@@ -80,9 +78,9 @@ <h1 id="{{ lower $method }}{{ $anchor }}">
 </table>
 
 <hr/>
-{{ partial "openapi/render-request"   (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "path" $path "anchor_base" $anchor ) }}
+{{ partial "openapi/render-request"   (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "anchor_base" $anchor ) }}
 <hr/>
-{{ partial "openapi/render-responses" (dict "responses"  $operation_data.responses  "path" $path "anchor_base" $anchor ) }}
+{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "anchor_base" $anchor ) }}
 
 </details>
 
diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html
index ecabfc05a..1cd263a30 100644
--- a/layouts/partials/openapi/render-parameters.html
+++ b/layouts/partials/openapi/render-parameters.html
@@ -5,7 +5,6 @@
   * `parameters`: OpenAPI data specifying the parameters
   * `type`: the type of parameters to render: "header, ""path", "query"
   * `caption`: caption to use for the table
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
 
   This template renders a single table containing parameters of the given type.
 
@@ -14,9 +13,7 @@
 {{ $parameters := .parameters }}
 {{ $type := .type }}
 {{ $caption := .caption }}
-{{ $path := .path }}
 
-{{ $parameters = partial "json-schema/resolve-refs" (dict "schema" $parameters "path" $path) }}
 {{ $parameters_of_type := where $parameters "in" $type }}
 
 {{ with $parameters_of_type }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index f41e062dc..d922b64e0 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -4,7 +4,6 @@
 
   * `parameters`: OpenAPI data specifying the parameters
   * `request_body`: OpenAPI data specifying the request body
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
   * `anchor_base`: a prefix to add to the HTML anchors generated for each object
 
   This template renders:
@@ -16,7 +15,6 @@
 
 {{ $parameters := .parameters }}
 {{ $request_body := .request_body }}
-{{ $path := .path }}
 {{ $anchor_base := .anchor_base }}
 
 <h2>Request</h2>
@@ -26,9 +24,9 @@ <h2>Request</h2>
     {{ if $parameters }}
 <h3>Request parameters</h3>
 
-        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "header" "caption" "header parameters" "path" .path) }}
-        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "path" "caption" "path parameters" "path" .path) }}
-        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "query" "caption" "query parameters" "path" .path) }}
+        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "header" "caption" "header parameters") }}
+        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "path" "caption" "path parameters") }}
+        {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "query" "caption" "query parameters") }}
 
     {{ end }}
 
@@ -42,8 +40,7 @@ <h3>Request body</h3>
             {{/*
                 Display the JSON schemas
             */}}
-            {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }}
-            {{ $schema := partial "json-schema/resolve-allof" $schema }}
+            {{ $schema := partial "json-schema/resolve-allof" $json_body.schema }}
 
             {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
             {{ range $additional_types }}
@@ -70,8 +67,7 @@ <h3>Request body example</h3>
             {{ $example := dict }}
 
             {{ if $body.schema }}
-                {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }}
-                {{ $schema := partial "json-schema/resolve-allof" $schema }}
+                {{ $schema := partial "json-schema/resolve-allof" $body.schema }}
 
                 {{ $example = partial "json-schema/resolve-example" $schema }}
             {{ end }}
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index dba7fa8bb..437e811a5 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -3,7 +3,6 @@
   Render the response part of a single HTTP API operation, given:
 
   * `responses`: OpenAPI data specifying the responses
-  * `path`: the path where this definition was found, to enable us to resolve "$ref"
   * `anchor_base`: a prefix to add to the HTML anchors generated for each object
 
   This template renders:
@@ -15,7 +14,6 @@
 */}}
 
 {{ $responses := .responses }}
-{{ $path := .path }}
 {{ $anchor_base := .anchor_base }}
 
 <h2>Responses</h2>
@@ -26,8 +24,6 @@ <h2>Responses</h2>
   <th class="col-status-description">Description</th>
  </thead>
 
-{{ $responses = partial "json-schema/resolve-refs" (dict "schema" $responses "path" $path) }}
-
 {{ range $code, $response := $responses }}
 
  <tr>
@@ -92,8 +88,7 @@ <h3>{{$code}} response</h3>
             {{ if or (eq $schema.type "object") (eq $schema.type "array") }}
                 {{ $example := partial "json-schema/resolve-example" $schema }}
                 {{ if $json_body.examples }}
-                    {{ $example = partial "json-schema/resolve-refs" (dict "schema" $json_body.examples "path" $path) }}
-                    {{ $example = $example.response.value }}
+                    {{ $example = $json_body.examples.response.value }}
                 {{ end }}
 
                 {{ $example_json := jsonify (dict "indent" "  ") $example }}
diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html
index 43d08b9e5..cc6463cf6 100644
--- a/layouts/shortcodes/http-api.html
+++ b/layouts/shortcodes/http-api.html
@@ -23,4 +23,7 @@
 {{ $base_url := (index $api_data.servers 0).variables.basePath.default }}
 {{ $path := delimit (slice "api" $spec $api) "/" }}
 
-{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }}
+{{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }}
+{{ $api_data := partial "json-schema/resolve-allof" $api_data }}
+
+{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }}

From 415faa298b6ba16c6df8a6483276dfc211fd9d92 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Fri, 29 Mar 2024 15:16:57 +0100
Subject: [PATCH 2/6] Enable strict $ref rule in OpenAPI validator
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 redocly.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/redocly.yaml b/redocly.yaml
index 263f0bcad..28dda2db9 100644
--- a/redocly.yaml
+++ b/redocly.yaml
@@ -1,10 +1,11 @@
 # See https://redocly.com/docs/cli/configuration/ for more information.
 extends:
-  - minimal
+  - recommended-strict
 rules:
   info-license: off
   security-defined: off
   operation-4xx-response: off
   no-invalid-media-type-examples: off
   no-path-trailing-slash: off
-  operation-2xx-response: off
\ No newline at end of file
+  operation-2xx-response: off
+  spec-strict-refs: error
\ No newline at end of file

From 5aa67086b58cbc2f080520cbb77930df1f41aa33 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Fri, 29 Mar 2024 15:20:02 +0100
Subject: [PATCH 3/6] Document use of $ref to compose examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 openapi_extensions.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/openapi_extensions.md b/openapi_extensions.md
index 15b93adc8..8a7146a9b 100644
--- a/openapi_extensions.md
+++ b/openapi_extensions.md
@@ -26,3 +26,8 @@ property, etc).
 
 A variation of the above: indicates changes to the associated parameter in
 particular Matrix specification versions.
+
+## Use of `$ref` inside examples
+
+Although the OpenAPI/JSON Schema specs only allow to use `$ref` to reference a
+whole example, we use it to compose examples from other examples.

From 765ca6100a08bf8b650e5535214e369356525324 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Fri, 29 Mar 2024 15:29:52 +0100
Subject: [PATCH 4/6] Fix schema path in event-fields shortcode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 layouts/shortcodes/event-fields.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/layouts/shortcodes/event-fields.html b/layouts/shortcodes/event-fields.html
index 91e2faf2a..e06d77eee 100644
--- a/layouts/shortcodes/event-fields.html
+++ b/layouts/shortcodes/event-fields.html
@@ -13,7 +13,7 @@
 */}}
 
 {{ $event := index .Site.Data "event-schemas" "schema" "core-event-schema" .Params.event_type }}
-{{ $path := "event-schemas/schema/core-event-schema" }}
+{{ $path := delimit (slice "event-schemas/schema/core-event-schema" .Params.event_type) "/" }}
 
 {{ $event = partial "json-schema/resolve-refs" (dict "schema" $event "path" $path) }}
 {{ $event := partial "json-schema/resolve-allof" $event }}

From dcc33eb2001fb44fb83ead3b4a6091d135f0227f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Fri, 29 Mar 2024 15:35:39 +0100
Subject: [PATCH 5/6] Add changelog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 changelogs/internal/newsfragments/1773.clarification | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelogs/internal/newsfragments/1773.clarification

diff --git a/changelogs/internal/newsfragments/1773.clarification b/changelogs/internal/newsfragments/1773.clarification
new file mode 100644
index 000000000..53d959d1c
--- /dev/null
+++ b/changelogs/internal/newsfragments/1773.clarification
@@ -0,0 +1 @@
+Simplify uses of `resolve-refs` partial.

From c446bb739b99aebe537593b251e568f575fd6f4f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Tue, 9 Apr 2024 18:53:02 +0200
Subject: [PATCH 6/6] Remove resolve-allOf
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 layouts/shortcodes/http-api.html | 1 -
 1 file changed, 1 deletion(-)

diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html
index cc6463cf6..28e764003 100644
--- a/layouts/shortcodes/http-api.html
+++ b/layouts/shortcodes/http-api.html
@@ -24,6 +24,5 @@
 {{ $path := delimit (slice "api" $spec $api) "/" }}
 
 {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }}
-{{ $api_data := partial "json-schema/resolve-allof" $api_data }}
 
 {{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }}