Update layouts for OpenAPI 3.1

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

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

layouts/partials/openapi/render-operation.html

@@ -64,7 +64,7 @@ <h1 id="{{ lower $method }}{{ $anchor }}">
 </table>
 
 <hr/>
-{{ 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 ) }}
 <hr/>
 {{ partial "openapi/render-responses" (dict "responses"  $operation_data.responses  "path" $path "anchor_base" $anchor ) }}
 

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

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 }}
 
 <h2>Request</h2>
 
-{{ if $parameters }}
+{{ if or $parameters $request_body }}
 
-    {{ $simple_parameters := where $parameters "in" "!=" "body"}}
-    {{ if $simple_parameters }}
+    {{ if $parameters }}
 <h3>Request parameters</h3>
 
-        {{ 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 }}
 <h3>Request body</h3>
-
-        {{/* 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 }}
 
 <h3>Request body example</h3>
-
-        {{ $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 }}

layouts/partials/openapi/render-responses.html

@@ -38,11 +38,19 @@ <h2>Responses</h2>
 </table>
 
 {{ 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 }}
 <h3>{{$code}} response</h3>
+            {{ 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 @@ <h3>{{$code}} response</h3>
         */}}
         {{ 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 @@ <h3>{{$code}} response</h3>
         */}}
         {{ 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 @@ <h3>{{$code}} response</h3>
 ```json
 {{ $example_json }}
 ```
+            {{ end }}
         {{ end }}
     {{ end }}
 {{ end }}

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