mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-13 06:54:10 +01:00
Deduplicate code for OpenAPI Media Type Objects
These are common to requests and responses and can be found in the `content` field. This also adds more locations to where we can find examples and makes sure that the order of where we look for them is consistent. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille
parent
25195b1001
commit
b11f246cb3
98
layouts/partials/openapi/render-media-type-objects.html
Normal file
98
layouts/partials/openapi/render-media-type-objects.html
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
{{/*
|
||||
|
||||
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.
|
||||
|
||||
*/}}
|
||||
|
||||
{{ $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 }}
|
||||
<p>Array of <code>{{ $type_of }}</code>.</p>
|
||||
{{ 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_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" }}
|
||||
<h3>Request body example</h3>
|
||||
{{ 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 }}
|
||||
|
|
@ -33,50 +33,8 @@
|
|||
|
||||
{{ if $request_body }}
|
||||
<h3>Request body</h3>
|
||||
{{/*
|
||||
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 }}
|
||||
|
||||
<h3>Request body example</h3>
|
||||
{{/*
|
||||
Show all the examples.
|
||||
*/}}
|
||||
{{ range $mime, $body := $request_body.content }}
|
||||
{{ $examples := slice }}
|
||||
|
||||
{{ if $body.schema }}
|
||||
{{ $examples = partial "json-schema/resolve-examples" $body.schema }}
|
||||
{{ end }}
|
||||
|
||||
{{ if and (eq ($examples | len) 0) $body.example }}
|
||||
{{/*
|
||||
If no examples were generated from the schema, fallback to the
|
||||
main example.
|
||||
*/}}
|
||||
{{ $examples = slice $body.example }}
|
||||
{{ end }}
|
||||
|
||||
{{ range $examples }}
|
||||
{{ partial "render-example" (dict "example" . "mime" $mime) }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ partial "openapi/render-media-type-objects" (dict "content" $request_body.content "kind" "request" "anchor_base" $anchor) }}
|
||||
{{ end }}
|
||||
|
||||
{{ else }}
|
||||
|
|
|
|||
|
|
@ -59,71 +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 }}
|
||||
<p>Array of <code>{{ $type_of }}</code>.</p>
|
||||
{{ 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 the examples. Currently this is only supported for arrays
|
||||
and objects.
|
||||
*/}}
|
||||
{{ if or (eq $schema.type "object") (eq $schema.type "array") }}
|
||||
{{ $examples := slice }}
|
||||
{{ if $json_body.examples }}
|
||||
{{ $examples = slice $json_body.examples.response.value }}
|
||||
{{ else }}
|
||||
{{ $examples = partial "json-schema/resolve-examples" $schema }}
|
||||
{{ end }}
|
||||
|
||||
{{ range $examples }}
|
||||
{{ partial "render-example" (dict "example" .) }}
|
||||
{{ end }}
|
||||
{{ 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 }}
|
||||
|
|
|
|||
Loading…
Reference in a new issue