Simplify uses of resolve-refs partial

changelogs/internal/newsfragments/1773.clarification

@@ -0,0 +1 @@
+Simplify uses of `resolve-refs` partial.

layouts/partials/openapi/render-api.html

@@ -5,23 +5,19 @@
   * `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 }}
 
     {{ $endpoint := delimit (slice $base_url $path_name ) "" }}
 
     {{/* note that a `paths` entry can be a $ref */}}
 
-    {{ $params := dict "endpoint" $endpoint "path" $path }}
+    {{ $params := dict "endpoint" $endpoint }}
 
     {{ with $path_data.get }}
 

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>
 

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

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

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

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

layouts/shortcodes/http-api.html

@@ -23,4 +23,6 @@
 {{ $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) }}
+
+{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }}

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.

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
+  operation-2xx-response: off
+  spec-strict-refs: error