diff --git a/changelogs/client_server/newsfragments/1756.clarification b/changelogs/client_server/newsfragments/1756.clarification new file mode 100644 index 000000000..918e87c19 --- /dev/null +++ b/changelogs/client_server/newsfragments/1756.clarification @@ -0,0 +1 @@ +Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses. diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index da1a69bd6..036522ded 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -1,27 +1,30 @@ {{/* - Render a table showing content type and description, given: + Render a table showing content types and their descriptions, given + two arrays with equal length: - * `content_type`: the content type as a string + * `content_types`: the content type strings - * `description`: the description as a string + * `descriptions`: the description strings */}} -{{ $content_type := .content_type }} -{{ $description := .description}} +{{ $content_types := .content_types }} +{{ $descriptions := .descriptions}} -{{ if $content_type }} +{{ if (gt (len $content_types) 0) }} + {{ range $idx, $content_type := $content_types }} - + + {{ end }}
Content-Type Description
{{ $content_type }}{{ $description | markdownify -}}{{ index $descriptions $idx | markdownify -}}
{{ end }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 5ef55c64e..f41e062dc 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -53,12 +53,13 @@

Request body

{{/* Show the content types and description. */}} - {{ $mimes := slice }} + {{ $mimes := slice }} + {{ $descriptions := slice }} {{ range $mime, $body := $request_body.content }} {{ $mimes = $mimes | append $mime }} + {{ $descriptions = $descriptions | append $request_body.description }} {{ end }} - {{ $content_type := delimit $mimes "|"}} - {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $request_body.description) }} + {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} {{ end }}

Request body example

diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 82c2f9547..dba7fa8bb 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -109,13 +109,12 @@

{{$code}} response

Show the content types and description. */}} {{ $mimes := slice }} - {{ $desc := "" }} + {{ $descriptions := slice }} {{ range $mime, $body := $response.content }} {{ $mimes = $mimes | append $mime }} - {{ $desc = $body.schema.description }} + {{ $descriptions = $descriptions | append $body.schema.description }} {{ end }} - {{ $content_type := delimit $mimes "|"}} - {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $desc) }} + {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} {{ end }} {{ end }} {{ end }}