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..9cfe62a7 --- /dev/null +++ b/layouts/partials/openapi/render-media-type-objects.html @@ -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 }} +

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_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 02d43625..88749cbf 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -33,50 +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 }} - {{ $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 }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index d64d1f9a..0e7f1324 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -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 }} -

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