Look for examples in all possible locations (#2076)
We used to only look for examples in a few (sometimes arbitrary) places, and we didn't support showing several examples in most cases. This is intended to fix this. In the process we try to deduplicate code to make sure that we use the same logic everywhere. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille
GitHub
parent
4ff9a851e6
commit
3adbfa30da
14 changed files with 226 additions and 220 deletions
104
layouts/partials/openapi/render-media-type-objects.html
Normal file
104
layouts/partials/openapi/render-media-type-objects.html
Normal file
|
|
@ -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 }}
|
||||
<p>Array of <code>{{ $type_of }}</code>.</p>
|
||||
{{ 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" }}
|
||||
<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,65 +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 }}
|
||||
{{ $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 }}
|
||||
|
|
|
|||
|
|
@ -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 }}
|
||||
<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 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 }}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue