wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2024-03-19 15:50:49 +01:00 • committed by GitHub
parent 0b43b5a343
commit 4d7e33ec26
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 140 additions and 163 deletions
Download patch file Download diff file Expand all files Collapse all files

11
layouts/partials/events/example.html
View file

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

6
layouts/partials/events/render-event.html
View file

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

22
layouts/partials/json-schema/resolve-refs.html
View file

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

4
layouts/partials/openapi/render-parameters.html
View file

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

6
layouts/partials/openapi/render-request.html
View file

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

5
layouts/partials/openapi/render-responses.html
View file

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

4
layouts/shortcodes/definition.html
View file

@ -22,10 +22,6 @@
{{ errorf "site data %s not found" $path }}
{{ end }}
{{/* The base path, which we use to resolve $ref, omits the last component */}}
{{ $pieces = first (sub (len $pieces) 1) $pieces}}
{{ $path = delimit $pieces "/" }}
{{/* Resolve $ref and allOf */}}
{{ $definition = partial "json-schema/resolve-refs" (dict "schema" $definition "path" $path) }}
{{ $definition = partial "json-schema/resolve-allof" $definition }}

2
layouts/shortcodes/event.html
View file

@ -25,7 +25,7 @@
*/}}
{{ $event_data := index .Site.Data "event-schemas" "schema" .Params.event }}
{{ $path := "event-schemas/schema" }}
{{ $path := delimit (slice "event-schemas/schema" .Params.event) "/" }}
{{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }}
{{ $event_data := partial "json-schema/resolve-allof" $event_data }}

2
layouts/shortcodes/http-api.html
View file

@ -21,6 +21,6 @@
{{ $api_data := index .Site.Data.api .Params.spec .Params.api }}
{{ $base_url := (index $api_data.servers 0).variables.basePath.default }}
{{ $path := delimit (slice "api" $spec) "/" }}
{{ $path := delimit (slice "api" $spec $api) "/" }}
{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }}

2
layouts/shortcodes/msgtypes.html
View file

@ -6,7 +6,6 @@
*/}}
{{ $path := "event-schemas/schema" }}
{{ $compact := false }}
{{/*
@ -40,6 +39,7 @@
{{ range $msgtypes }}
{{ $event_data := index $site_data "event-schemas" "schema" . }}
{{ $path := delimit (slice "event-schemas/schema" .) "/" }}
{{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }}
{{ $event_data := partial "json-schema/resolve-allof" $event_data }}