| Release date | {{ .Date | time.Format ":date_long" }} |
{{ end -}}
{{ $checklist := .OutputFormats.Get "checklist" -}}
diff --git a/layouts/partials/events/example.html b/layouts/partials/events/example.html
index 90752fbd..c24cd66b 100644
--- a/layouts/partials/events/example.html
+++ b/layouts/partials/events/example.html
@@ -13,10 +13,4 @@
{{ $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 }}
-
-```json
-{{ $example_json }}
-```
+{{ partial "render-example" (dict "example" $example_content) }}
diff --git a/layouts/partials/json-schema/resolve-allof.html b/layouts/partials/json-schema/resolve-allof.html
index b8b81e7d..61a03c3f 100644
--- a/layouts/partials/json-schema/resolve-allof.html
+++ b/layouts/partials/json-schema/resolve-allof.html
@@ -24,6 +24,14 @@
{{ range $original }}
{{ $resolved := partial "json-schema/resolve-allof" . }}
+ {{ if reflect.IsSlice $resolved }}
+ {{/*
+ If $resolved is a slice, `append` will add the items of $resolved to
+ $ret, but we want to add $resolved itself to $ret, so we always wrap
+ it into another slice.
+ */}}
+ {{ $resolved = slice $resolved }}
+ {{ end }}
{{ $ret = $ret | append $resolved }}
{{ end }}
{{ else if reflect.IsMap $original }}
diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html
deleted file mode 100644
index 8fa98400..00000000
--- a/layouts/partials/json-schema/resolve-example.html
+++ /dev/null
@@ -1,46 +0,0 @@
-{{/*
-
- For complex objects, example content is sometimes attached to the
- object's individual properties (and subproperties...), so to get
- a complete example for the whole object we need to iterate through
- its properties (and subproperties...) and assemble them.
-
- That's what this template does.
-
-*/}}
-
-{{ $this_object := . }}
-
-{{ $example := $this_object.example }}
-
-{{ if not $example }}
-
- {{ if eq $this_object.type "object" }}
- {{ $example = dict }}
-
- {{ range $key, $property := $this_object.properties}}
- {{ $this_property_example := partial "json-schema/resolve-example" $property }}
- {{ if $this_property_example }}
- {{ $example = merge (dict $key $this_property_example) $example }}
- {{ end }}
- {{ end }}
-
- {{ else if eq $this_object.type "array" }}
-
- {{/* the "items" within an array can either be an object (where we have a
- list of items which match the schema), or a list (for tuple
- validation, where each item has a different schema).
-
- TODO: support tuple validation here.
- */}}
- {{ if reflect.IsMap $this_object.items }}
- {{ $items_example := partial "json-schema/resolve-example" $this_object.items }}
- {{ if $items_example }}
- {{ $example = slice $items_example }}
- {{ end }}
- {{ end }}
- {{ end }}
-
-{{ end }}
-
-{{ return $example }}
diff --git a/layouts/partials/json-schema/resolve-examples.html b/layouts/partials/json-schema/resolve-examples.html
new file mode 100644
index 00000000..dd126540
--- /dev/null
+++ b/layouts/partials/json-schema/resolve-examples.html
@@ -0,0 +1,71 @@
+{{/*
+
+ Find examples in the given JSON schema.
+
+ Tries to find examples in the `examples` and `example` keys of the schema
+ first.
+
+ If it doesn't succeed, iterates through the properties and subproperties to
+ collect their examples, to merge them into a complete example for the whole
+ object.
+
+ Parameter: the JSON schema to extract the examples from.
+
+*/}}
+
+{{ $this_object := . }}
+{{ $examples := slice }}
+
+{{ if $this_object.examples }}
+ {{/* This is an array of examples, we can just use it */}}
+ {{ $examples = $this_object.examples }}
+{{ else if $this_object.example }}
+ {{ $examples = slice $this_object.example }}
+{{ else }}
+ {{/* Resolve the nested examples */}}
+ {{ if eq $this_object.type "object" }}
+ {{ $example := dict }}
+
+ {{ range $key, $property := $this_object.properties}}
+ {{ $this_property_examples := partial "json-schema/resolve-examples" $property }}
+ {{/*
+ It would be too complex to handle several nested examples,
+ just use the first one.
+ */}}
+ {{ with index $this_property_examples 0 }}
+ {{ $example = merge (dict $key .) $example }}
+ {{ end }}
+ {{ end }}
+
+ {{/*
+ Add the assembled example to the list if either (a) the example is
+ non-empty, or (b) the object itself is meant to be empty (so an
+ empty example is correct).
+ */}}
+ {{ if (or $example (not $this_object.properties)) }}
+ {{ $examples = slice $example }}
+ {{ end }}
+
+ {{ else if eq $this_object.type "array" }}
+
+ {{/* the "items" within an array can either be an object (where we have a
+ list of items which match the schema), or a list (for tuple
+ validation, where each item has a different schema).
+
+ TODO: support tuple validation here.
+ */}}
+ {{ if reflect.IsMap $this_object.items }}
+ {{ $items_examples := partial "json-schema/resolve-examples" $this_object.items }}
+ {{/*
+ It would be too complex to handle several nested examples,
+ just use the first one.
+ */}}
+ {{ with index $items_examples 0 }}
+ {{ $examples = slice (slice .) }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+
+{{ end }}
+
+{{ return $examples }}
diff --git a/layouts/partials/json-schema/resolve-refs.html b/layouts/partials/json-schema/resolve-refs.html
index 9a36e413..7479498a 100644
--- a/layouts/partials/json-schema/resolve-refs.html
+++ b/layouts/partials/json-schema/resolve-refs.html
@@ -69,6 +69,14 @@
{{ range $schema }}
{{ $resolved := partial "json-schema/resolve-refs" (dict "schema" . "path" $path) }}
+ {{ if reflect.IsSlice $resolved }}
+ {{/*
+ If $resolved is a slice, `append` will add the items of $resolved to
+ $result_slice, but we want to add $resolved itself to $result_slice,
+ so we wrap it into another slice.
+ */}}
+ {{ $resolved = slice $resolved }}
+ {{ end }}
{{ $result_slice = $result_slice | append $resolved }}
{{ end }}
diff --git a/layouts/partials/openapi/render-media-type-objects.html b/layouts/partials/openapi/render-media-type-objects.html
new file mode 100644
index 00000000..7c48320e
--- /dev/null
+++ b/layouts/partials/openapi/render-media-type-objects.html
@@ -0,0 +1,104 @@
+{{/*
+
+ Render a map of [Media Type Objects](https://spec.openapis.org/oas/v3.1.1#media-type-object).
+ This map can be found as the `content` field of requests and responses.
+
+ Parameters:
+
+ * `content`: A map of MIME type to Media Type Object
+ * `kind`: the kind of object that is rendered, either `request` or `response`.
+ * `anchor_base`: a prefix to add to the HTML anchors generated for each object
+
+ This template renders:
+
+ * Object tables if the map contains an `application/json` MIME type, or a
+ table with the MIME types and the corresponding description of the object.
+ * The examples of the Media Type Objects.
+
+*/}}
+
+{{/*
+ Request and response bodies can have several content types. If there is a
+ JSON type, we display that; otherwise we just show the content types and
+ descriptions.
+*/}}
+{{ $json_body := index .content "application/json" }}
+{{ if $json_body }}
+ {{/*
+ Display the JSON schemas
+ */}}
+
+ {{ $schema := $json_body.schema }}
+
+ {{/*
+ All this is to work out how to express the content of the response
+ in the case where it is an array.
+ */}}
+ {{ if eq $schema.type "array" }}
+ {{ $type_of := "" }}
+ {{ if $schema.items.anyOf }}
+ {{ $types := slice }}
+ {{ range $schema.items.anyOf }}
+ {{ if .title }}
+ {{ $types = $types | append .title}}
+ {{ else }}
+ {{ $types = $types | append .type }}
+ {{ end }}
+ {{ end }}
+ {{ $type_of = delimit $types ", "}}
+ {{ else }}
+ {{ $type_of = $schema.items.title }}
+ {{ end }}
+Array of {{ $type_of }}.
+ {{ end }}
+
+ {{/*
+ Render object tables for any objects referenced in the request/response.
+
+ This will be a no-op for request/response body types which aren't
+ objects or arrays.
+ */}}
+ {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" .anchor_base) }}
+ {{ range $additional_types }}
+ {{ partial "openapi/render-object-table" . }}
+ {{ end }}
+{{ else }}
+ {{/*
+ Show the content types and description.
+ */}}
+ {{ partial "openapi/render-content-type" (dict "content_types" .content) }}
+{{ end }}
+
+{{/*
+ Show all the examples.
+*/}}
+{{ if eq .kind "request" }}
+Request body example
+{{ end }}
+
+{{ range $mime, $body := .content }}
+ {{ $examples := slice }}
+
+ {{/*
+ Find the examples to display, with the following priority:
+
+ 1. The `examples` field
+ 2. The `example` field
+ 3. The examples in the `schema` field
+ */}}
+ {{ if $body.examples }}
+ {{/* This is a map of string to Example Object */}}
+ {{ range $key, $example := $body.examples }}
+ {{/* The example is in the `value` field of the object */}}
+ {{ $examples = $examples | append (slice $example.value) }}
+ {{ end }}
+ {{ else if $body.example }}
+ {{ $examples = slice $body.example }}
+ {{ else if $body.schema }}
+ {{ $examples = partial "json-schema/resolve-examples" $body.schema }}
+ {{ end }}
+
+ {{ range $examples }}
+ {{ partial "render-example" (dict "example" . "mime" $mime) }}
+ {{ end }}
+{{ end }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index 80b352c6..88749cbf 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -33,65 +33,8 @@
{{ if $request_body }}
Request body
- {{/*
- A request can have several content types.
- */}}
- {{ $json_body := index $request_body.content "application/json" }}
- {{ if $json_body }}
- {{/*
- Display the JSON schemas
- */}}
- {{ $schema := $json_body.schema }}
- {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
- {{ range $additional_types }}
- {{ partial "openapi/render-object-table" . }}
- {{ end }}
- {{ else }}
- {{/*
- Show the content types and description.
- */}}
- {{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }}
- {{ end }}
-
-Request body example
- {{/*
- Show all the examples.
- */}}
- {{ range $mime, $body := $request_body.content }}
- {{ $example := dict }}
-
- {{ if $body.schema }}
- {{ $example = partial "json-schema/resolve-example" $body.schema }}
- {{ end }}
-
- {{ if and (eq ($example | len) 0) $body.example }}
- {{/*
- If no example was generated from the schema, fallback to the
- main example.
- */}}
- {{ $example = $body.example }}
- {{ end }}
-
- {{ if eq $mime "application/json" }}
- {{ $example_json := jsonify (dict "indent" " ") $example }}
- {{ $example_json = replace $example_json "\\u003c" "<" }}
- {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-```json
-{{ $example_json }}
-```
- {{ else }}
- {{ $example = $example | safeHTML }}
- {{/*
- We need to set a language for the code otherwise the styling
- is different than other examples.
- */}}
-```json
-{{ $example }}
-```
- {{ end }}
-
- {{ end }}
+ {{ partial "openapi/render-media-type-objects" (dict "content" $request_body.content "kind" "request" "anchor_base" $anchor) }}
{{ end }}
{{ else }}
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index 084e9481..0e7f1324 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -59,72 +59,6 @@
{{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }}
{{ end }}
- {{/*
- A response can have several content types.
- */}}
- {{ $json_body := index $response.content "application/json" }}
- {{ if $json_body }}
- {{/*
- Display the JSON schemas
- */}}
-
- {{ $schema := $json_body.schema }}
-
- {{/*
- All this is to work out how to express the content of the response
- in the case where it is an array.
- */}}
- {{ if eq $schema.type "array" }}
- {{ $type_of := "" }}
- {{ if $schema.items.anyOf }}
- {{ $types := slice }}
- {{ range $schema.items.anyOf }}
- {{ if .title }}
- {{ $types = $types | append .title}}
- {{ else }}
- {{ $types = $types | append .type }}
- {{ end }}
- {{ end }}
- {{ $type_of = delimit $types ", "}}
- {{ else }}
- {{ $type_of = $schema.items.title }}
- {{ end }}
-Array of {{ $type_of }}.
- {{ end }}
-
-
- {{/*
- render object tables for any objects referenced in the
- response. (This will be a no-op for response types which aren't
- objects or arrays.)
- */}}
- {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
- {{ range $additional_types }}
- {{ partial "openapi/render-object-table" . }}
- {{ end }}
-
- {{/*
- render an example. currently this is only supported for arrays and objects.
- */}}
- {{ if or (eq $schema.type "object") (eq $schema.type "array") }}
- {{ $example := partial "json-schema/resolve-example" $schema }}
- {{ if $json_body.examples }}
- {{ $example = $json_body.examples.response.value }}
- {{ end }}
-
- {{ $example_json := jsonify (dict "indent" " ") $example }}
- {{ $example_json = replace $example_json "\\u003c" "<" }}
- {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```
- {{ end }}
- {{ else }}
- {{/*
- Show the content types and description.
- */}}
- {{ partial "openapi/render-content-type" (dict "content_types" $response.content) }}
- {{ end }}
+ {{ partial "openapi/render-media-type-objects" (dict "content" $response.content "kind" "response" "anchor_base" $anchor) }}
{{ end }}
{{ end }}
diff --git a/layouts/partials/render-example.html b/layouts/partials/render-example.html
new file mode 100644
index 00000000..1f6c18fb
--- /dev/null
+++ b/layouts/partials/render-example.html
@@ -0,0 +1,40 @@
+{{/*
+
+ Renders an example to be included in HTML, with support for pretty-printing
+ JSON.
+
+ Parameters:
+
+ * `example`: the example
+ * `mime`: the mime type of the example. Used to pretty-print JSON and for
+ syntax highlighting. If it is not provided, it is assumed to be
+ `application/json`.
+
+*/}}
+
+{{ $example := .example }}
+
+{{/*
+ We need to convert the mime type to a recognized language.
+ For simplicity we only support JSON, which is also the default. Other mime
+ types are not highlighted.
+*/}}
+{{ $language := "json" }}
+
+{{ if (and .mime (ne .mime "application/json")) }}
+ {{/*
+ `no-highlight` treats the value as plain text, but still styles the code
+ block like the ones with proper syntax highlighting.
+ */}}
+ {{ $language = "no-highlight" }}
+{{ end }}
+
+{{ if eq $language "json" }}
+ {{ $example = jsonify (dict "indent" " ") $example }}
+ {{ $example = replace $example "\\u003c" "<" }}
+ {{ $example = replace $example "\\u003e" ">" }}
+{{ end }}
+
+```{{ $language }}
+{{ $example | safeHTML }}
+```
diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html
index 10ad0e87..1a9643d9 100644
--- a/layouts/shortcodes/definition.html
+++ b/layouts/shortcodes/definition.html
@@ -58,13 +58,14 @@
{{ partial "openapi/render-object-table" . }}
{{end}}
+{{ $examples := partial "json-schema/resolve-examples" $definition }}
+{{ if $examples }}
Examples
-{{ $example := partial "json-schema/resolve-example" $definition }}
-
-```json
-{{ jsonify (dict "indent" " ") $example }}
-```
+ {{ range $examples }}
+ {{ partial "render-example" (dict "example" .) }}
+ {{ end }}
+{{ end }}
diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh
index 678af60f..9c80b059 100755
--- a/scripts/generate-changelog.sh
+++ b/scripts/generate-changelog.sh
@@ -44,8 +44,18 @@ outputs:
- html
- checklist
date: $(date -Idate)
----
EOF
+
+ # Add the commit hash for the unstable versions. It is used to generate a
+ # link to the commit on the repository.
+ if [ "$VERSION" == "vUNSTABLE" ]; then
+ echo "params:"
+ echo " commit: $(git rev-parse --short HEAD)"
+ fi
+
+ # Close the frontmatter.
+ echo "---"
+
# Remove trailing whitespace (such as our intentionally blank RST headings)
sed -e "s/[ ]*$//" rendered.md
} > ../content/changelog/$FILENAME
diff --git a/static/.well-known/funding-manifest-urls b/static/.well-known/funding-manifest-urls
new file mode 100644
index 00000000..1b14b420
--- /dev/null
+++ b/static/.well-known/funding-manifest-urls
@@ -0,0 +1 @@
+https://matrix.org/funding.json
|---|