Resolve reference objects in parameters

This requires us to pass down $root_schema and $path.
matrix-org · Mar 13, 2024 · 5c32de9 · 5c32de9
1 parent 013b33a
commit 5c32de9
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 20 deletions.
diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html
@@ -21,7 +21,7 @@
 
     {{/* note that a `paths` entry can be a $ref */}}
 
-    {{ $params := dict "endpoint" $endpoint "path" $path }}
+    {{ $params := dict "endpoint" $endpoint "path" $path "root_schema" $api_data }}
 
     {{ with $path_data.get }}
 

diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html
@@ -6,6 +6,7 @@
   * `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"
+  * `root_schema`: the root schema object where this definition was found, to enable us to resolve local "$ref" references
 
   This template renders the operation as a `<section>` containing:
 
@@ -22,6 +23,7 @@
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
 {{ $path := .path }}
+{{ $root_schema := .root_schema }}
 {{ $anchor := anchorize $endpoint }}
 
 <section class="rendered-data http-api {{ $method }}">
@@ -80,7 +82,7 @@ <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 "path" $path "anchor_base" $anchor "root_schema" $root_schema ) }}
 <hr/>
 {{ partial "openapi/render-responses" (dict "responses"  $operation_data.responses  "path" $path "anchor_base" $anchor ) }}
 

diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html
@@ -3,8 +3,10 @@
   Render the parameters of a given type, given:
 
   * `parameters`: OpenAPI data specifying the parameters
-  * `type`: the type of parameters to render: "header, ""path", "query"
+  * `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"
+  * `root_schema`: the root schema object where this definition was found, to enable us to resolve local "$ref" references
 
   This template renders a single table containing parameters of the given type.
 
@@ -13,14 +15,23 @@
 {{ $parameters := .parameters }}
 {{ $type := .type }}
 {{ $caption := .caption }}
-
-{{ $parameters_of_type := where $parameters "in" $type }}
-
-{{ with $parameters_of_type }}
-
-    {{/* build a dict mapping from name->parameter, which render-object-table expects */}}
-    {{ $param_dict := dict }}
-    {{ range $parameter := . }}
+{{ $root_schema := .root_schema }}
+{{ $path := .path }}
+
+{{/* build a dict mapping from name->parameter, which render-object-table expects */}}
+{{ $param_dict := dict }}
+
+{{ range $parameter := $parameters }}
+    {{/*
+        Per https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operation-object:
+        the parameters can be reference objects; resolve them now.
+    */}}
+    {{ $parameter = partial "openapi/resolve-ref-object" (dict
+        "schema" $parameter
+        "root_schema" $root_schema
+        "path" $path
+    ) }}
+    {{ if (eq $parameter.in $type) }}
         {{/*
             merge the schema at the same level as the rest of the other fields because that is
             what `render-object-table` expects. Put the schema first so examples in it are
@@ -29,8 +40,7 @@
         {{ $param := merge $parameter.schema $parameter }}
         {{ $param_dict = merge $param_dict (dict $parameter.name $param )}}
     {{ end }}
-
-    {{/* and render the parameters */}}
-    {{ partial "openapi/render-object-table" (dict "title" $caption "properties" $param_dict) }}
-
 {{ end }}
+
+{{/* and render the parameters */}}
+{{ partial "openapi/render-object-table" (dict "title" $caption "properties" $param_dict) }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
@@ -5,6 +5,7 @@
   * `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"
+  * `root_schema`: the root schema object where this definition was found, to enable us to resolve local "$ref" references
   * `anchor_base`: a prefix to add to the HTML anchors generated for each object
 
   This template renders:
@@ -17,6 +18,7 @@
 {{ $parameters := .parameters }}
 {{ $request_body := .request_body }}
 {{ $path := .path }}
+{{ $root_schema := .root_schema }}
 {{ $anchor_base := .anchor_base }}
 
 <h2>Request</h2>
@@ -26,10 +28,28 @@ <h2>Request</h2>
     {{ if $parameters }}
 <h3>Request parameters</h3>
 
-        {{ 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") }}
-
+        {{ partial "openapi/render-parameters" (dict
+            "parameters" $parameters
+            "type" "header"
+            "caption" "header parameters"
+            "path" $path
+            "root_schema" $root_schema
+        ) }}
+        {{ partial "openapi/render-parameters" (dict
+            "parameters" $parameters
+            "type" "path"
+            "caption" "path parameters"
+            "path" $path
+            "root_schema" $root_schema
+        ) }}
+        {{ partial "openapi/render-parameters" (dict
+            "parameters" $parameters
+            "type" "query"
+            "caption" "query parameters"
+            "root_schema" $root_schema
+            "path" $path
+            "root_schema" $root_schema
+        ) }}
     {{ end }}
 
     {{ if $request_body }}
@@ -53,7 +73,7 @@ <h3>Request body</h3>
             {{/*
                 Show the content types and description.
             */}}
-            {{ $mimes := slice }}  
+            {{ $mimes := slice }}
             {{ range $mime, $body := $request_body.content }}
                 {{ $mimes = $mimes | append $mime }}
             {{ end }}