archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Simplify uses of `resolve-refs` partial (#1773)

Browse Source 
* Use the resolve-refs partial as soon as possible

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.

* Enable strict $ref rule in OpenAPI validator

* Document use of $ref to compose examples

* Fix schema path in event-fields shortcode

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
pull/1781/head
Kévin Commaille 8 months ago committed by GitHub
parent 2ea8e0f514
commit 2678370f2c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 22 additions and 31 deletions
Show Stats Download Patch File Download Diff File

1
changelogs/internal/newsfragments/1773.clarification
Unescape Escape View File

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

6
layouts/partials/openapi/render-api.html
Unescape Escape View File

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

6
layouts/partials/openapi/render-operation.html
Unescape Escape View File

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

3
layouts/partials/openapi/render-parameters.html
Unescape Escape View File

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

14
layouts/partials/openapi/render-request.html
Unescape Escape View File

@ -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 @@
{{ 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 @@
{{/*
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 @@
{{ $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 }}

7
layouts/partials/openapi/render-responses.html
Unescape Escape View File

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

2
layouts/shortcodes/event-fields.html
Unescape Escape View File

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

4
layouts/shortcodes/http-api.html
Unescape Escape View File

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

5
openapi_extensions.md
Unescape Escape View File

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

5
redocly.yaml
Unescape Escape View File

@ -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
Write Preview
Loading…
Cancel
Save