render-codeblock-openapi.html

{{- $page := .Page }}
{{- $pageVersion := .Page.Store.Get "versionShort" }}
{{- if and (not $pageVersion) (strings.HasPrefix .Page.RelPermalink "/arangodb/") }}
  {{- $pageVersion = (partialCached "version-short.html" .Page.RelPermalink .Page.RelPermalink) }}
{{- end }}
{{- $title := .Page.Scratch.Get "currentHeadline" }}
{{- $endpoint := printf "%s/openapi" site.Params.arangoproxyUrl }}
{{- $service := "arangodb" }}
{{- $apiVersions := slice }}
{{- $body := "" }}

{{- $matches := findRESubmatch `(?ms)^---\r?\n(.*?)^---\r?\n(.*)$` .Inner 2 }}
{{- if $matches }}
  {{- $frontmatter := index (index $matches 0) 1 | transform.Unmarshal }}
  {{- $body = index (index $matches 0) 2 }}
  {{- $service = $frontmatter.service | default $service }}
  {{- $apiVersions = $frontmatter.apiVersions }}
  {{- if eq $service "arangodb" }}
    {{- if or (not $apiVersions) (not (reflect.IsSlice $apiVersions)) (eq (len $apiVersions) 0) }}
      {{- errorf "OpenAPI front matter: service is %s but apiVersions is missing, not an array, or empty (got %T: %v)" $service $apiVersions $apiVersions }}
    {{- end }}
  {{- end }}
{{- else }}
  {{- $body = .Inner }}
  {{- /* $service defaults to "arangodb"; apiVersions depend on ArangoDB version (3.10/3.11→v0, 3.12→v0+v1, 4.0→v1) */}}
  {{- if eq $service "arangodb" }}
    {{- if or (eq $pageVersion "3.10") (eq $pageVersion "3.11") }}
      {{- $apiVersions = slice "v0" }}
    {{- else if eq $pageVersion "3.12" }}
      {{- $apiVersions = slice "v0" }}{{/* TODO: Add "v1" again for 3.12.10 */}}
    {{- else if eq $pageVersion "4.0" }}
      {{- $apiVersions = slice "v1" }}
    {{- else }}
      {{- errorf "OpenAPI front matter: Unsupported ArangoDB page version %q — add an apiVersions mapping for this version" $pageVersion }}
    {{- end }}
  {{- end }}
{{- end }}

{{- $linkMap := dict }}
{{- range $match := findRESubmatch `\[([^\]]+)\]\((.*?)\)` $body }}
  {{- $url := index $match 2 }}
  {{- $isRemote := ne (urls.Parse $url).Scheme "" }}
  {{- if not $isRemote }}
    {{- $absPath := urls.RelRef $page $url }}
    {{- $absPathUnaliased := replaceRE "^/arangodb/(?:stable|devel)/" (printf "/arangodb/%s/" $pageVersion) $absPath 1 }}
    {{- $absUrl := printf "https://docs.arango.ai%s" $absPathUnaliased }}
    {{- $newLink := printf "[%s](%s)" (index $match 1) $absUrl }}
    {{- $linkMap = merge $linkMap (dict (index $match 0) $newLink) }}
  {{- end }}
{{- end }}
{{- $innerAbsLinks := $body }}
{{- range $old, $new := $linkMap }}
  {{- $innerAbsLinks = replace $innerAbsLinks $old $new }}
{{- end }}

{{- $remote := resources.GetRemote $endpoint (dict
    "method" "post"
    "body" $innerAbsLinks
    "headers" (dict 
      "Content-Type" "application/json"
      "Endpoint-Title" $title
      "Service-Name" $service
      "API-Versions" ($apiVersions | jsonify)
      "Page-Version" (cond (eq $service "arangodb") $pageVersion "")
    )
  )
}}
{{- $title = $title | urlize }}
{{- $yamlBlock := $body | transform.Unmarshal }}
{{- with $yamlBlock }}
  <div class="openapi">
  {{- range $path, $methods := .paths }}
    {{- range $method, $items := $methods }}
      {{- $displayPath := $path }}
      {{- if (eq $service "arangodb") }}
        {{- if (in $apiVersions "v0") }}
          {{- /* Omit prefix for 3.12 docs because older versions don't have a versioned API */}}
        {{- else if (in $apiVersions "v1") }}
          {{- $displayPath = printf "/_arango/v1%s" $path }}
        {{- else if (in $apiVersions "experimental") }}
          {{- $displayPath = printf "/_arango/experimental%s" $path }}
        {{- end }}
      {{- end }}
      {{- partial "shortcodes/endpoint.html" (dict
        "Method" ($method | upper)
        "Url"    (printf "http%s://<EXTERNAL_ENDPOINT>:8529%s" (cond (eq $service "arangodb") "" "s") $displayPath | replaceRE "#.*" "")
      ) }}
      <div class="openapi-description regular-font">
        {{- $items.description | $page.RenderString }}
      </div>
      {{- with .parameters }}
        {{- template "renderParameters" dict "title" $title "content" . "page" $page }}
      {{- end }}
      {{- with .requestBody }}
        {{- template "renderRequestBody" dict "title" $title "content" . "page" $page }}
      {{- end }}
      {{- with .responses }}
        {{- template "renderResponses" dict "title" $title "content" .  "page" $page }}
      {{- end }}
    {{- end }}
  {{- end }}
  </div>
{{- end }}

{{- define "renderParameters" }}
  {{- $title := .title }}
  {{- $content := .content }}
  {{- $page := .page }}
  <div class="openapi-parameters regular-font">
    <div class="openapi-table-title">Path Parameters</div>
    <div>
      <ul class="openapi-table">
      {{- range $k, $v := $content }}
        {{- template "renderParameter" dict "title" $title "prop" $v.name "value" $v "category" "path" "page" $page}}
      {{- end }}
      </ul>
    </div>
  </div>
  <div class="openapi-parameters regular-font">
    <div class="openapi-table-title">Query Parameters</div>
    <div>
      <ul class="openapi-table">
      {{- range $k, $v := $content }}
        {{- template "renderParameter" dict "title" $title "prop" $v.name "value" $v "category" "query" "page" $page}}
      {{- end }}
      </ul>
    </div>
  </div>
  <div class="openapi-parameters regular-font">
    <div class="openapi-table-title">HTTP Headers</div>
    <div>
      <ul class="openapi-table">
      {{- range $k, $v := $content }}
        {{- template "renderParameter" dict "title" $title "prop" $v.name "value" $v "category" "header" "page" $page}}
      {{- end }}
      </ul>
    </div>
  </div>
{{- end }}

{{- define "renderRequestBody" }}
  {{- $title := printf "%s_%s" .title "body" }}
  {{- $content := .content }}
  {{- $page := .page }}
  <div class="openapi-parameters regular-font">
    {{- $contentType := "" }}
    {{- $schemaType := "" }}
    {{- $schemaDefaultSet := false }}
    {{- $schemaDefault := "" }}
    {{- range $k, $v := $content.content }}
      {{- $contentType = $k }}
      {{- $schemaType = $v.schema.type }}
      {{- $schemaDefaultSet = isset $v.schema "default" }}
      {{- $schemaDefault = $v.schema.default }}
    {{- end }}
    <div class="openapi-table-title">Request Body <span class="openapi-content-type">{{ $contentType }}</span>
    {{- with $schemaType }}
      {{- if ne . "array" }} <span class="openapi-property-type">{{ . }}
        {{- if $schemaDefaultSet }} <span style="font-weight: normal">(default: <code>{{ $schemaDefault | jsonify }}</code>)</span>{{ end }}</span>
      {{- end }}
    {{- end }}
    </div>
    <div>
      <ul class="openapi-table">
      {{- range $k, $v := $content.content }}
        {{- if eq $v.schema.type "array" }}
          {{- $required := false }}
          {{- template "renderProperty" dict "title" $title "prop" "" "value" $v.schema "required" $required "page" $page "isResponse" false }}
        {{- else }}
          {{- with $v.schema.description }}{{ . | $page.RenderString }}{{ end }}
          {{- range $prop, $value := $v.schema.properties}}
            {{- $required := in $v.schema.required $prop }}
            {{- template "renderProperty" dict "title" $title "prop" $prop "value" $value "required" $required "page" $page "isResponse" false }}
          {{- end }}
        {{- end }}
      {{- end }}
      </ul>
    </div>
  </div>
{{- end }}

{{- define "renderResponses" }}
  {{- $title := .title }}
  {{- $content := .content }}
  {{- $page := .page }}
  {{- $statusMap := dict
    "200" "OK"
    "201" "Created"
    "202" "Accepted"
    "204" "No Content"
    "304" "Not Modified"
    "400" "Bad Request"
    "401" "Unauthorized"
    "403" "Forbidden"
    "404" "Not Found"
    "405" "Method Not Allowed"
    "408" "Request Timeout"
    "409" "Conflict"
    "410" "Gone"
    "412" "Precondition Failed"
    "500" "Internal Server Error"
    "501" "Not Implemented"
    "503" "Service Unavailable"
    "504" "Gateway Timeout"
    "default" "(Varying HTTP status codes)"
  }}
  <div class="responses regular-font">
    <div class="openapi-table-title">Responses</div>
    <div class="openapi-responses">
      <ul class="openapi-table">
      {{- range $status, $content := $content }}
        {{- $statusId :=  printf "%s_res_%s" $title $status }}
        <li class="openapi-table-row regular-font">
          <details  id="{{ printf "%s" $statusId }}">
          <summary class="openapi-prop collapsed">
            <span class="openapi-property-name bold-text">{{ $status }}</span>
            {{- $statusDescription := index $statusMap $status }}
            {{- if not $statusDescription }}{{ errorf "OpenAPI: %v missing in HTTP status code mapping" $status }}{{ end }}
            <span class="openapi-property-type bold-text">{{ $statusDescription }}</span>
            <a class="openapi-property-link" href="{{ printf "#%s" $statusId }}"><i class="fa fa-link"></i></a>
          </summary>
            {{- $description := $content.description | $page.RenderString }}
            <div class="openapi-prop-content">
              <p class="regular-font">{{ $description }}</p>
              {{- if $content.content }}
                <ul class="openapi-table">
                  {{- $contentType := "" }}
                  {{- $schemaType := "" }}
                  {{- range $k, $v := $content.content }}
                    {{- $contentType = $k }}
                    {{- $schemaType = $v.schema.type }}
                  {{- end }}
                  <div class="openapi-table-title">Response Body <span class="openapi-content-type">{{ $contentType }}</span>
                    {{- with $schemaType }}{{ if ne . "array" }} <span class="openapi-property-type">{{ . }}</span>{{ end }}{{ end -}}
                  </div>
                  {{- range $k, $v := $content.content }}
                    {{- if eq $v.schema.type "array" }}
                      {{- $required := false }}
                      {{- template "renderProperty" dict "title" $statusId "prop" "" "value" $v.schema "required" $required "page" $page "isResponse" true}}
                    {{- else }}
                      {{- with $v.schema.description }}{{ . | $page.RenderString }}{{ end }}
                      {{- range $prop, $value := $v.schema.properties}}
                        {{- $required := in $v.schema.required $prop }}
                        {{- template "renderProperty" dict "title" $statusId "prop" $prop "value" $value "required" $required "page" $page "isResponse" true}}
                      {{- end }}
                    {{- end }}
                  {{- end }}
                </ul>
              {{- end }}
            </div>
          </details>
        </li>       
      {{- end }}
      </ul>
    </div>
  </div>
{{- end }}

{{- define "renderParameter" }}
  {{- $title := .title }}
  {{- $category := .category }}
  {{- $prop := .prop }}
  {{- $value := .value }}
  {{- $page := .page }}
  
  {{- if eq $category $value.in }}
    {{- $structName := "" }}
    {{- $anchor := printf "%s_%s_%s" $title $category $prop }}
    <li class="openapi-table-row regular-font">
      <details  id="{{ $anchor }}">
        <summary class="openapi-prop collapsed">
          <span class="openapi-property-name bold-text">{{ $prop }}{{ if $value.required }}*{{ end }}</span>
          <span class="openapi-property-type">
            <span class="bold-text">{{ $value.schema.type }}</span>
            {{- if isset $value.schema "default" }} (default: <code>{{ $value.schema.default | jsonify }}</code>){{ end }}
          </span>
          <a class="openapi-property-link" href="{{ printf "#%s" $anchor }}"><i class="fa fa-link"></i></a>
        </summary>
        {{- $description := $value.description | $page.RenderString }}
        <div class="openapi-prop-content">
          {{- if isset $value.schema "const" }}
            <p class="regular-font">Set this to the value: <code>{{ $value.schema.const | jsonify }}</code></p>
          {{- else if isset $value.schema "enum" }}
            <p class="regular-font">Possible values:
              {{- range $i, $val := $value.schema.enum }}
                {{- if gt $i 0 }},{{ end }} <code>{{ . | jsonify }}</code>
              {{- else }}
                <em>(none)</em>
              {{- end }}
            </p>
          {{- end }}
          <p class="regular-font">{{ $description }}</p>
          {{- if isset $value.schema "example" }}
            <p class="regular-font">Example: <code>{{ $value.schema.example | jsonify }}</code></p>
          {{- end }}
        </div>
      </details>
    </li>
  {{- end }}
{{- end }}

{{- define "renderProperty" }}
  {{- $title := .title }}
  {{- $prop := .prop }}
  {{- $value := .value }}
  {{- $required := .required }}
  {{- $page := .page }}
  {{- $isResponse := .isResponse }}

  {{- $type := $value.type }}
  {{- $anchor := printf "%s_%s" $title $prop }}
  <li class="openapi-table-row regular-font">
    {{- if and (eq $value.type "array") ($value.items.type) }}
      {{- $type = printf "array of %ss" $value.items.type }}
    {{- else if eq $value.type "object" }}
      {{- $type = "object" }}
    {{- end }}
    <details id="{{ $anchor }}">
      <summary class="openapi-prop collapsed">
        <span class="openapi-property-name bold-text {{ if eq $prop "" }} no-border {{ end }} ">{{ $prop }}{{ if $required }}*{{ end }}</span>
        <span class="openapi-property-type">
          <span class="bold-text">{{ $type }}</span>
          {{- if isset $value "default" }} (default: <code>{{ $value.default | jsonify }}</code>){{ end }}
        </span>
        <a class="openapi-property-link" href="#{{ $anchor }}"><i class="fa fa-link"></i></a>
      </summary>
      {{- $description := $value.description | $page.RenderString }}
      <div class="openapi-prop-content">
        {{- if isset $value "const" }}
          <p class="regular-font">{{ if $isResponse }}The value is always:{{ else }}Set this to the value:{{ end }} <code>{{ $value.const | jsonify }}</code></p>
        {{- else if isset $value "enum" }}
          <p class="regular-font">Possible values:
            {{- range $i, $val := $value.enum }}
              {{- if gt $i 0 }},{{ end }} <code>{{ . | jsonify }}</code>
            {{- else }}
              <em>(none)</em>
            {{- end }}
          </p>
        {{- end }}
        {{- if and ($value.items) (isset $value.items "const") }}
          <p class="regular-font">{{ if $isResponse }}Each element has the value:{{ else }}Set each element to the value:{{ end }} <code>{{ $value.items.const | jsonify }}</code></p>
        {{- else if and ($value.items) (isset $value.items "enum") }}
          <p class="regular-font">Possible values in array:
            {{- range $i, $val := $value.items.enum }}
              {{- if gt $i 0 }},{{ end }} <code>{{ . | jsonify }}</code>
            {{- else }}
              <em>(none)</em>
            {{- end }}
          </p>
        {{- end }}
        <p class="regular-font">{{ $description }}</p>
        {{- if isset $value "example" }}
          <p class="regular-font">Example: <code>{{ $value.example | jsonify }}</code></p>
        {{- end }}
        {{- if $value.properties }}
          <ul class="openapi-table">
          {{- range $k, $v := $value.properties }}
            {{- $required = in $value.required $k }}
            {{- template "renderProperty" dict "title" $anchor "prop" $k "value" $v "required" $required "page" $page "isResponse" $isResponse }}
          {{- end }}
          </ul>
        {{- end }}
        {{- if $value.items.properties }}
          <ul class="openapi-table">
          {{- range $k, $v := $value.items.properties }}
            {{- $required = in $value.items.required $k }}
            {{- template "renderProperty" dict "title" $anchor "prop" $k "value" $v "required" $required "page" $page "isResponse" $isResponse }}
          {{- end }}
          </ul>
        {{- end }}
      </div>
    </details>
  </li>
{{- end }}