Add support for $ref URIs containing fragments in OpenAPI definitions and JSON schemas (#1751)

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

layouts/partials/events/example.html

@@ -1,13 +1,18 @@
 {{/*
 
-  Renders an event example.  Resolves `$ref`s, serializes as JSON, and ensures
+  Renders an event example. Resolves `$ref`s, serializes as JSON, and ensures
   that it can be included in HTML.
 
-  This partial is called with the example event object as its context.
+  Parameters:
+
+    * `schema`: the schema of the example
+    * `name`: the name of the example
 
 */}}
 
-{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" . "path" "event-schemas/examples") }}
+{{ $path := delimit (slice "event-schemas/examples" .name) "/" }}
+
+{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .schema "path" $path) }}
 {{ $example_json := jsonify (dict "indent" "  ") $example_content }}
 {{ $example_json = replace $example_json "\\u003c" "<" }}
 {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}

layouts/partials/events/render-event.html

@@ -77,7 +77,7 @@
     */}}
     {{ if $desired_example_name }}
         {{ if eq $example_name $desired_example_name }}
-            {{ partial "events/example" $example }}
+            {{ partial "events/example" (dict "schema" $example "name" $example_name) }}
         {{ end }}
     {{/*
       If `$desired_example_name` is not given, we will include any
@@ -86,7 +86,7 @@
       the event name includes a "$".
     */}}
     {{ else if eq $event_name $example_name }}
-        {{ partial "events/example" $example }}
+        {{ partial "events/example" (dict "schema" $example "name" $example_name) }}
     {{/*
       If `$desired_example_name` is not given, we will include any
       examples whose first part (before "$") matches the event name
@@ -96,7 +96,7 @@
         {{ $pieces := split $example_name "$" }}
         {{ $example_base_name := index $pieces 0 }}
         {{ if eq $event_name $example_base_name }}
-             {{ partial "events/example" $example }}
+             {{ partial "events/example" (dict "schema" $example "name" $example_name) }}
         {{ end }}
     {{ end }}
 {{ end }}

layouts/partials/json-schema/resolve-refs.html

@@ -1,7 +1,10 @@
 {{/*
 
   Resolves the `$ref` JSON schema keyword, by recursively replacing
-  it with the object it points to.
+  it with the object it points to, given:
+
+  * `schema`: the schema where the references should be resolved
+  * `path`: the path of the file containing the schema
 
   This template uses [`Scratch`](https://gohugo.io/functions/scratch/)
   rather than a normal `dict` because with `dict` you can't replace key values:
@@ -20,8 +23,12 @@
     {{ $scratch.Set "result_map" dict }}
 
     {{ $ref_value := index $schema "$ref"}}
-    {{ if $ref_value}}
-        {{ $full_path := path.Join $path $ref_value }}
+    {{ if $ref_value }}
+        {{ $uri := urls.Parse $path }}
+        {{ $ref_uri := urls.Parse $ref_value }}
+        {{ $full_uri := $uri.ResolveReference $ref_uri }}
+
+        {{ $full_path := strings.TrimPrefix "/" $full_uri.Path }}
         {{/*
           Apparently Hugo doesn't give us a nice way to split the extension off a filename.
         */}}
@@ -30,11 +37,18 @@
 
         {{ $ref := index site.Data $pieces }}
 
+        {{/* If there is a fragment, follow the JSON Pointer */}}
+        {{ if $full_uri.Fragment }}
+            {{ $fragment := strings.TrimPrefix "/" $full_uri.Fragment }}
+            {{ $pieces := split $fragment "/" }}
+            {{ $ref = index $ref $pieces }}
+        {{ end }}
+
         {{ $new_path := (path.Split $full_path).Dir}}
         {{ $result_map := partial "json-schema/resolve-refs" (dict "schema" $ref "path" $new_path)}}
         {{ if $result_map}}
             {{ $scratch.Set "result_map" $result_map }}
-        {{end }}
+        {{ end }}
     {{ end }}
 
 

layouts/partials/openapi/render-parameters.html

@@ -5,6 +5,7 @@
   * `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.
 
@@ -13,7 +14,9 @@
 {{ $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 }}
@@ -32,5 +35,4 @@
 
     {{/* and render the parameters */}}
     {{ partial "openapi/render-object-table" (dict "title" $caption "properties" $param_dict) }}
-
 {{ end }}

layouts/partials/openapi/render-request.html

@@ -26,9 +26,9 @@
     {{ 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) }}
+        {{ 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) }}
 
     {{ end }}
 

layouts/partials/openapi/render-responses.html

@@ -26,6 +26,8 @@
   <th class="col-status-description">Description</th>
  </thead>
 
+{{ $responses = partial "json-schema/resolve-refs" (dict "schema" $responses "path" $path) }}
+
 {{ range $code, $response := $responses }}
 
  <tr>
@@ -49,8 +51,7 @@
                 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 }}
 
             {{/*
             All this is to work out how to express the content of the response