diff --git a/changelogs/internal/newsfragments/1876.clarification b/changelogs/internal/newsfragments/1876.clarification new file mode 100644 index 00000000..9f840914 --- /dev/null +++ b/changelogs/internal/newsfragments/1876.clarification @@ -0,0 +1 @@ +Render added/changed in info on request and response content types. diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index d0a6e5bb..92ca6caa 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -715,8 +715,9 @@ components: bytes: content: application/octet-stream: - example: - description: The content to be uploaded. + schema: + description: The content to be uploaded. + example: required: true responses: uploadTooLarge: diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index 96033e16..a7c90e1a 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -1,16 +1,12 @@ {{/* - Render a table showing content types and their descriptions, given - two arrays with equal length: + Render a table showing content types and their descriptions, given: - * `content_types`: the content type strings - - * `descriptions`: the description strings + * `content_types`: OpenAPI data specifying the content types as a dictionary of the form {string: {"schema": JsonSchema}} */}} {{ $content_types := .content_types }} -{{ $descriptions := .descriptions}} {{ if (gt (len $content_types) 0) }} @@ -21,10 +17,14 @@ Description - {{ range $idx, $content_type := $content_types }} + {{ range $mime, $body := $content_types }} - {{ $content_type }} - {{ index $descriptions $idx | markdownify -}} + {{ $mime }} + + {{ $body.schema.description | markdownify -}} + {{ if (index $body.schema "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $body.schema "x-addedInMatrixVersion")) }}{{ end -}} + {{ if (index $body.schema "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $body.schema "x-changedInMatrixVersion")) }}{{ end -}} + {{ end }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 5fa0c255..92811f12 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -50,13 +50,7 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} - {{ $descriptions := slice }} - {{ range $mime, $body := $request_body.content }} - {{ $mimes = $mimes | append $mime }} - {{ $descriptions = $descriptions | append $request_body.description }} - {{ end }} - {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} + {{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }} {{ end }}

Request body example

diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 80dcb582..f26110b4 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -123,13 +123,7 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} - {{ $descriptions := slice }} - {{ range $mime, $body := $response.content }} - {{ $mimes = $mimes | append $mime }} - {{ $descriptions = $descriptions | append $body.schema.description }} - {{ end }} - {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} + {{ partial "openapi/render-content-type" (dict "content_types" $response.content) }} {{ end }} {{ end }} {{ end }}