diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html index 8af18e97..541fe10d 100644 --- a/layouts/partials/openapi/render-api.html +++ b/layouts/partials/openapi/render-api.html @@ -21,7 +21,7 @@ {{/* note that a `paths` entry can be a $ref */}} - {{ $params := dict "endpoint" $endpoint "path" $path }} + {{ $params := dict "endpoint" $endpoint "path" $path "root_schema" $api_data }} {{ with $path_data.get }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 253e2efe..3d5a472d 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -6,6 +6,7 @@ * `endpoint`: the endpoint * `operation_data`: the OpenAPI data for the operation * `path`: the path where this definition was found, to enable us to resolve "$ref" + * `root_schema`: the root schema object where this definition was found, to enable us to resolve local "$ref" references This template renders the operation as a `
` containing: @@ -22,6 +23,7 @@ {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} {{ $path := .path }} +{{ $root_schema := .root_schema }} {{ $anchor := anchorize $endpoint }}
@@ -80,7 +82,7 @@
-{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "path" $path "anchor_base" $anchor ) }} +{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "path" $path "anchor_base" $anchor "root_schema" $root_schema ) }}
{{ 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 925b0197..e874d86b 100644 --- a/layouts/partials/openapi/render-parameters.html +++ b/layouts/partials/openapi/render-parameters.html @@ -3,8 +3,10 @@ Render the parameters of a given type, given: * `parameters`: OpenAPI data specifying the parameters - * `type`: the type of parameters to render: "header, ""path", "query" + * `type`: the type of parameters to render: "header", "path", "query" * `caption`: caption to use for the table + * `path`: the path where this definition was found, to enable us to resolve "$ref" + * `root_schema`: the root schema object where this definition was found, to enable us to resolve local "$ref" references This template renders a single table containing parameters of the given type. @@ -13,14 +15,23 @@ {{ $parameters := .parameters }} {{ $type := .type }} {{ $caption := .caption }} - -{{ $parameters_of_type := where $parameters "in" $type }} - -{{ with $parameters_of_type }} - - {{/* build a dict mapping from name->parameter, which render-object-table expects */}} - {{ $param_dict := dict }} - {{ range $parameter := . }} +{{ $root_schema := .root_schema }} +{{ $path := .path }} + +{{/* build a dict mapping from name->parameter, which render-object-table expects */}} +{{ $param_dict := dict }} + +{{ range $parameter := $parameters }} + {{/* + Per https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operation-object: + the parameters can be reference objects; resolve them now. + */}} + {{ $parameter = partial "openapi/resolve-ref-object" (dict + "schema" $parameter + "root_schema" $root_schema + "path" $path + ) }} + {{ if (eq $parameter.in $type) }} {{/* 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 @@ -29,8 +40,7 @@ {{ $param := merge $parameter.schema $parameter }} {{ $param_dict = merge $param_dict (dict $parameter.name $param )}} {{ end }} - - {{/* and render the parameters */}} - {{ partial "openapi/render-object-table" (dict "title" $caption "properties" $param_dict) }} - {{ end }} + +{{/* and render the parameters */}} +{{ partial "openapi/render-object-table" (dict "title" $caption "properties" $param_dict) }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 3d4b0381..24b09d5e 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -5,6 +5,7 @@ * `parameters`: OpenAPI data specifying the parameters * `request_body`: OpenAPI data specifying the request body * `path`: the path where this definition was found, to enable us to resolve "$ref" + * `root_schema`: the root schema object where this definition was found, to enable us to resolve local "$ref" references * `anchor_base`: a prefix to add to the HTML anchors generated for each object This template renders: @@ -17,6 +18,7 @@ {{ $parameters := .parameters }} {{ $request_body := .request_body }} {{ $path := .path }} +{{ $root_schema := .root_schema }} {{ $anchor_base := .anchor_base }}

Request

@@ -26,10 +28,28 @@ {{ if $parameters }}

Request 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") }} - + {{ partial "openapi/render-parameters" (dict + "parameters" $parameters + "type" "header" + "caption" "header parameters" + "path" $path + "root_schema" $root_schema + ) }} + {{ partial "openapi/render-parameters" (dict + "parameters" $parameters + "type" "path" + "caption" "path parameters" + "path" $path + "root_schema" $root_schema + ) }} + {{ partial "openapi/render-parameters" (dict + "parameters" $parameters + "type" "query" + "caption" "query parameters" + "root_schema" $root_schema + "path" $path + "root_schema" $root_schema + ) }} {{ end }} {{ if $request_body }} @@ -53,7 +73,7 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} + {{ $mimes := slice }} {{ range $mime, $body := $request_body.content }} {{ $mimes = $mimes | append $mime }} {{ end }}