diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index a93dc0ac4..75f346997 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -75,8 +75,8 @@ {{/* Add any nested objects referenced in this object's `items` */}} - {{ if reflect.IsSlice $this_object.items}} - {{ range $idx, $item := $this_object.items }} + {{ if $this_object.items.anyOf }} + {{ range $idx, $item := $this_object.items.anyOf }} {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $item "additional_objects" $additional_objects diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 1e4806714..6486f39c7 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -64,7 +64,7 @@


-{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "path" $path "anchor_base" $anchor ) }} +{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "path" $path "anchor_base" $anchor ) }}
{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "path" $path "anchor_base" $anchor ) }} diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html index b7861b7f2..0e643a259 100644 --- a/layouts/partials/openapi/render-parameters.html +++ b/layouts/partials/openapi/render-parameters.html @@ -21,7 +21,13 @@ {{/* build a dict mapping from name->parameter, which render-object-table expects */}} {{ $param_dict := dict }} {{ range $parameter := . }} - {{ $param_dict = merge $param_dict (dict $parameter.name $parameter )}} + {{/* + merge the schema at the same level as the rest of the other fields because that is + what `render-object-table` expects. Put the schema first so examples in it are + overwritten. + */}} + {{ $param := merge $parameter.schema $parameter }} + {{ $param_dict = merge $param_dict (dict $parameter.name $param )}} {{ end }} {{/* and render the parameters */}} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index be39fa38c..36b846da6 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -3,6 +3,7 @@ Render the request part of a single HTTP API operation, given: * `parameters`: OpenAPI/Swagger data specifying the parameters + * `request_body`: OpenAPI/Swagger data specifying the request body * `path`: the path where this definition was found, to enable us to resolve "$ref" * `anchor_base`: a prefix to add to the HTML anchors generated for each object @@ -14,48 +15,57 @@ */}} {{ $parameters := .parameters }} +{{ $request_body := .request_body }} {{ $path := .path }} {{ $anchor_base := .anchor_base }}

Request

-{{ if $parameters }} +{{ if or $parameters $request_body }} - {{ $simple_parameters := where $parameters "in" "!=" "body"}} - {{ if $simple_parameters }} + {{ if $parameters }}

Request parameters

- {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "header" "caption" "header parameters") }} - {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "path" "caption" "path parameters") }} - {{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "query" "caption" "query parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "header" "caption" "header parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "path" "caption" "path parameters") }} + {{ partial "openapi/render-parameters" (dict "parameters" $parameters "type" "query" "caption" "query parameters") }} {{ end }} - {{ $body_parameters := where $parameters "in" "body"}} - {{ if $body_parameters }} + {{ if $request_body }}

Request body

- - {{/* at most one body param is allowed by the spec */}} - {{ $body_parameter := index $body_parameters 0 }} - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body_parameter.schema "path" $path) }} - {{ $schema := partial "json-schema/resolve-allof" $schema }} - - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} - {{ $additional_types = uniq $additional_types }} - {{ range $additional_types }} - {{ partial "openapi/render-object-table" . }} + {{/* + A request can have several content types. Only show the schema for JSON. + */}} + {{ $json_body := index $request_body.content "application/json" }} + {{ if $json_body }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types = uniq $additional_types }} + {{ range $additional_types }} + {{ partial "openapi/render-object-table" . }} + {{ end }} {{ end }}

Request body example

- - {{ $example := partial "json-schema/resolve-example" $schema }} - {{ $example_json := jsonify (dict "indent" " ") $example }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + {{/* + Show all the examples. + */}} + {{ range $mime, $body := $request_body.content }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-allof" $schema }} + + {{ $example := partial "json-schema/resolve-example" $schema }} + {{ $example_json := jsonify (dict "indent" " ") $example }} + {{ $example_json = replace $example_json "\\u003c" "<" }} + {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} ```json {{ $example_json }} ``` + {{ end }} {{ end }} {{ else }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 9c59b0f2d..9ef643e58 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -38,11 +38,19 @@

Responses

{{ range $code, $response := $responses }} - {{ if $response.schema }} - + {{/* + A response can have several content types so only insert the title once. + */}} + {{ $is_title_set := false }} + {{ range $content_type, $content := $response.content }} + {{ if $content.schema }} + + {{ if not $is_title_set }} + {{ $is_title_set = true }}

{{$code}} response

+ {{ end }} - {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $response.schema "path" $path) }} + {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $content.schema "path" $path) }} {{ $schema := partial "json-schema/resolve-allof" $schema }} {{/* @@ -51,9 +59,9 @@

{{$code}} response

*/}} {{ if eq $schema.type "array" }} {{ $type_of := "" }} - {{ if reflect.IsSlice $schema.items }} + {{ if $schema.items.anyOf }} {{ $types := slice }} - {{ range $schema.items }} + {{ range $schema.items.anyOf }} {{ if .title }} {{ $types = $types | append .title}} {{ else }} @@ -84,9 +92,9 @@

{{$code}} response

*/}} {{ if or (eq $schema.type "object") (eq $schema.type "array") }} {{ $example := partial "json-schema/resolve-example" $schema }} - {{ if $response.examples }} - {{ $example = partial "json-schema/resolve-refs" (dict "schema" $response.examples "path" $path) }} - {{ $example = index $example "application/json" }} + {{ if $content.examples }} + {{ $example = partial "json-schema/resolve-refs" (dict "schema" $content.examples "path" $path) }} + {{ $example = $example.response.value }} {{ end }} {{ $example_json := jsonify (dict "indent" " ") $example }} @@ -96,6 +104,7 @@

{{$code}} response

```json {{ $example_json }} ``` + {{ end }} {{ end }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html index 32e0ad41f..2668b1abc 100644 --- a/layouts/shortcodes/http-api.html +++ b/layouts/shortcodes/http-api.html @@ -20,7 +20,7 @@ {{ $api := .Params.api}} {{ $api_data := index .Site.Data.api .Params.spec .Params.api }} -{{ $base_url := $api_data.basePath }} +{{ $base_url := (index $api_data.servers 0).variables.basePath.default }} {{ $path := delimit (slice "api" $spec) "/" }} {{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "path" $path) }}