mirror of
https://github.com/docker/docs.git
synced 2026-11-04 10:01:00 +00:00
docs: migrate AI Governance API reference (#26125)
## Summary Vendor the OpenAPI 3.2 specification merged in docker/governor-services#755 and move AI Governance onto the unified API reference renderer while preserving its existing URLs. This supersedes #26067, which vendors an earlier upstream revision and retains the legacy renderer. @netlify /reference/api/ai-governance/latest/ [Deploy preview](https://deploy-preview-26125--docsdocker.netlify.app/reference/api/ai-governance/latest/) Generated by Codex
This commit is contained in:
David Karlsson authored and 
GitHub committed
1 parent
71fa064271
commit
5c18bca350
13 files changed
+128
-1181
No files matched your search
@@ -1,139 +0,0 @@
|
||||
{{/* Build a curl command for an OpenAPI operation.
|
||||
|
||||
Input dict:
|
||||
api — unmarshaled spec root
|
||||
op — operation object
|
||||
method — http method (lowercase string)
|
||||
path — path string (e.g. "/orgs/{org_name}/policies")
|
||||
sharedParams — already-resolved path-level parameters
|
||||
|
||||
Output: a multi-line curl command string (line-continued with " \\\n ").
|
||||
Path placeholders are filled from parameter examples when available;
|
||||
unresolved path params fall back to `<name>`. Query params without an
|
||||
example are omitted. Bearer-auth schemes contribute an Authorization
|
||||
header with the literal `$TOKEN` placeholder.
|
||||
*/}}
|
||||
{{- $api := .api -}}
|
||||
{{- $op := .op -}}
|
||||
{{- $method := .method -}}
|
||||
{{- $path := .path -}}
|
||||
{{- $sharedParams := .sharedParams -}}
|
||||
|
||||
{{/* Combine path-level + operation-level parameters, resolving $refs. */}}
|
||||
{{- $params := $sharedParams -}}
|
||||
{{- with index $op "parameters" -}}
|
||||
{{- range . -}}
|
||||
{{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}}
|
||||
{{- $params = $params | append $p -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
|
||||
{{/* Substitute path placeholders. */}}
|
||||
{{- $url := $path -}}
|
||||
{{- range $params -}}
|
||||
{{- if eq .in "path" -}}
|
||||
{{- $val := printf "<%s>" .name -}}
|
||||
{{- with .example -}}{{- $val = . | string -}}{{- end -}}
|
||||
{{- with .examples -}}
|
||||
{{- $picked := false -}}
|
||||
{{- with index . "default" -}}
|
||||
{{- with .value -}}
|
||||
{{- $val = . | string -}}{{- $picked = true -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if not $picked -}}
|
||||
{{- range . -}}
|
||||
{{- if not $picked -}}
|
||||
{{- with .value -}}
|
||||
{{- $val = . | string -}}{{- $picked = true -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- $url = replace $url (printf "{%s}" .name) $val -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
|
||||
{{/* Append query string from query parameters that have examples. */}}
|
||||
{{- $qs := slice -}}
|
||||
{{- range $params -}}
|
||||
{{- if eq .in "query" -}}
|
||||
{{- $val := "" -}}
|
||||
{{- with .example -}}{{- $val = . | string -}}{{- end -}}
|
||||
{{- with .examples -}}
|
||||
{{- $picked := false -}}
|
||||
{{- with index . "default" -}}
|
||||
{{- with .value -}}
|
||||
{{- $val = . | string -}}{{- $picked = true -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if not $picked -}}
|
||||
{{- range . -}}
|
||||
{{- if not $picked -}}
|
||||
{{- with .value -}}
|
||||
{{- $val = . | string -}}{{- $picked = true -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if $val -}}
|
||||
{{- $qs = $qs | append (printf "%s=%s" .name $val) -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if $qs -}}{{- $url = printf "%s?%s" $url (delimit $qs "&") -}}{{- end -}}
|
||||
|
||||
{{/* Prepend base URL from the first server entry. */}}
|
||||
{{- $base := "" -}}
|
||||
{{- with index $api.servers 0 -}}{{- $base = .url -}}{{- end -}}
|
||||
{{- $fullURL := printf "%s%s" $base $url -}}
|
||||
|
||||
{{- $lines := slice (printf "curl -X %s '%s'" (upper $method) $fullURL) -}}
|
||||
|
||||
{{/* Bearer auth header if the spec defines a bearer scheme. */}}
|
||||
{{- $hasBearer := false -}}
|
||||
{{- with $api.components -}}
|
||||
{{- with .securitySchemes -}}
|
||||
{{- range . -}}
|
||||
{{- if and (eq .type "http") (eq .scheme "bearer") -}}
|
||||
{{- $hasBearer = true -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if $hasBearer -}}
|
||||
{{- $lines = $lines | append "-H 'Authorization: Bearer $TOKEN'" -}}
|
||||
{{- end -}}
|
||||
|
||||
{{/* Request body example. Picks the first content type declared. */}}
|
||||
{{- with $op.requestBody -}}
|
||||
{{- $body := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}}
|
||||
{{- $ct := "" -}}
|
||||
{{- $media := dict -}}
|
||||
{{- range $name, $m := $body.content -}}
|
||||
{{- if not $ct -}}{{- $ct = $name -}}{{- $media = $m -}}{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if $ct -}}
|
||||
{{- $lines = $lines | append (printf "-H 'Content-Type: %s'" $ct) -}}
|
||||
{{- $example := "" -}}
|
||||
{{- with $media.examples -}}
|
||||
{{- with index . "default" -}}
|
||||
{{- with .value -}}{{- $example = . | jsonify -}}{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if not $example -}}
|
||||
{{- range . -}}
|
||||
{{- if not $example -}}
|
||||
{{- with .value -}}{{- $example = . | jsonify -}}{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if $example -}}
|
||||
{{- $lines = $lines | append (printf "-d '%s'" $example) -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- return (delimit $lines " \\\n ") -}}
|
||||
@@ -1,86 +0,0 @@
|
||||
{{/* Right-rail navigation for an OpenAPI reference page.
|
||||
|
||||
Input: the unmarshaled spec root (plain map from transform.Unmarshal).
|
||||
|
||||
Lists Authentication, every tag with its operations (linking to the same
|
||||
anchors the operation cards expose), and the Schemas section heading.
|
||||
*/}}
|
||||
{{- $api := . -}}
|
||||
{{- $paths := $api.paths -}}
|
||||
{{- $methods := slice "get" "post" "put" "patch" "delete" -}}
|
||||
{{- $methodColors := dict
|
||||
"get" "text-blue-700 dark:text-blue-300"
|
||||
"post" "text-green-700 dark:text-green-300"
|
||||
"put" "text-yellow-700 dark:text-yellow-300"
|
||||
"patch" "text-yellow-700 dark:text-yellow-300"
|
||||
"delete" "text-red-700 dark:text-red-300"
|
||||
-}}
|
||||
|
||||
|
||||
<p
|
||||
class="mb-3 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400"
|
||||
>
|
||||
On this page
|
||||
</p>
|
||||
<ul class="space-y-1">
|
||||
{{- with $api.components }}
|
||||
{{- if .securitySchemes }}
|
||||
<li>
|
||||
<a
|
||||
href="#authentication"
|
||||
class="block py-0.5 text-gray-700 hover:text-blue-600 dark:text-gray-300 dark:hover:text-blue-400"
|
||||
>
|
||||
Authentication
|
||||
</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- range $api.tags }}
|
||||
{{- $tagName := .name }}
|
||||
<li class="mt-3">
|
||||
<a
|
||||
href="#tag-{{ $tagName | urlize }}"
|
||||
class="block py-0.5 text-xs font-semibold tracking-wider text-gray-500 uppercase hover:text-blue-600 dark:text-gray-400 dark:hover:text-blue-400"
|
||||
>
|
||||
{{ $tagName | title }}
|
||||
</a>
|
||||
<ul class="mt-1 space-y-0.5">
|
||||
{{- range $path, $item := $paths }}
|
||||
{{- range $methods }}
|
||||
{{- $method := . }}
|
||||
{{- with index $item $method }}
|
||||
{{- $op := . }}
|
||||
{{- if in $op.tags $tagName }}
|
||||
{{- $label := $op.summary | default $op.operationId | default $path }}
|
||||
<li>
|
||||
<a
|
||||
href="#operation-{{ $op.operationId }}"
|
||||
class="flex items-baseline gap-2 py-0.5 text-gray-700 hover:text-blue-600 dark:text-gray-300 dark:hover:text-blue-400"
|
||||
>
|
||||
<span
|
||||
class="{{ index $methodColors $method }} w-12 flex-none font-mono text-[10px] font-bold uppercase"
|
||||
>{{ upper $method }}</span
|
||||
>
|
||||
<span class="min-w-0 truncate">{{ $label }}</span>
|
||||
</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
</ul>
|
||||
</li>
|
||||
{{- end }}
|
||||
{{- with $api.components }}
|
||||
{{- if .schemas }}
|
||||
<li class="mt-3">
|
||||
<a
|
||||
href="#schemas"
|
||||
class="block py-0.5 text-xs font-semibold tracking-wider text-gray-500 uppercase hover:text-blue-600 dark:text-gray-400 dark:hover:text-blue-400"
|
||||
>
|
||||
Schemas
|
||||
</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
</ul>
|
||||
@@ -1,26 +0,0 @@
|
||||
{{/* Resolve a possibly-$ref'd OpenAPI node against the spec root.
|
||||
|
||||
Input dict:
|
||||
api — the unmarshaled spec root (plain map from transform.Unmarshal)
|
||||
node — the node to resolve; may be a map, slice, primitive, or nil
|
||||
|
||||
Returns:
|
||||
- if node is a map containing a "$ref" key, returns the target node
|
||||
reached by walking the JSON-Pointer fragment (only internal "#/" refs
|
||||
are supported)
|
||||
- otherwise returns node unchanged
|
||||
*/}}
|
||||
{{- $node := .node -}}
|
||||
{{- if reflect.IsMap $node -}}
|
||||
{{- with index $node "$ref" -}}
|
||||
{{- if hasPrefix . "#/" -}}
|
||||
{{- $parts := after 1 (split . "/") -}}
|
||||
{{- $cur := $.api -}}
|
||||
{{- range $parts -}}
|
||||
{{- $cur = index $cur . -}}
|
||||
{{- end -}}
|
||||
{{- $node = $cur -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- return $node -}}
|
||||
@@ -1,700 +0,0 @@
|
||||
{{/* Wide-mode API reference layout.
|
||||
|
||||
Reads the colocated *.yaml Page Resource, unmarshals it into a plain Hugo
|
||||
map with transform.Unmarshal, and renders the OpenAPI 3 spec inline using
|
||||
Docker docs styling. Overrides baseof's "main" block so the article spans
|
||||
the full available width; the built-in right-rail TOC is replaced with a
|
||||
custom endpoint navigator (partials/api-ref/nav.html) sticky-pinned to
|
||||
the viewport.
|
||||
|
||||
$ref nodes are resolved on the fly through partials/api-ref/resolve.html;
|
||||
no oapi-codegen or third-party JS runtime is involved.
|
||||
*/}}
|
||||
|
||||
{{ define "main" }}
|
||||
{{- $specRes := .Resources.GetMatch "*.yaml" -}}
|
||||
{{- if not $specRes -}}
|
||||
{{- errorf "api-reference: no .yaml resource found alongside %s" .File.Path -}}
|
||||
{{- end -}}
|
||||
{{- $api := $specRes | transform.Unmarshal -}}
|
||||
|
||||
|
||||
<div class="flex w-full min-w-0 gap-8">
|
||||
<div class="min-w-0 flex-1">
|
||||
{{ partial "breadcrumbs.html" . }}
|
||||
<h1 data-pagefind-weight="10" class="mb-2 text-3xl font-bold">
|
||||
{{ .Title | safeHTML }}
|
||||
</h1>
|
||||
{{ with .Description }}
|
||||
<p class="text-gray-600 dark:text-gray-400">{{ . }}</p>
|
||||
{{ end }}
|
||||
{{ template "api-ref-meta" (dict "api" $api "spec" $specRes) }}
|
||||
{{ partialCached "md-dropdown.html" "-" "-" }}
|
||||
|
||||
{{ template "api-ref-overview" $api }}
|
||||
{{ template "api-ref-auth" $api }}
|
||||
{{ template "api-ref-tags" $api }}
|
||||
{{ template "api-ref-schemas" $api }}
|
||||
</div>
|
||||
|
||||
<aside class="hidden w-56 flex-none lg:block">
|
||||
<nav
|
||||
class="sticky top-20 max-h-[calc(100vh-6rem)] overflow-y-auto text-sm"
|
||||
>
|
||||
{{ partial "api-ref/nav.html" $api }}
|
||||
</nav>
|
||||
</aside>
|
||||
</div>
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Meta strip: version, base URL, download link ──────────────────────── */}}
|
||||
{{ define "api-ref-meta" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $spec := .spec -}}
|
||||
<div class="mt-4 flex flex-wrap items-center gap-x-6 gap-y-2 text-sm">
|
||||
{{- with $api.info }}
|
||||
{{- with .version }}
|
||||
<div>
|
||||
<span class="font-medium text-gray-500 dark:text-gray-400"
|
||||
>Version</span
|
||||
>
|
||||
<code
|
||||
class="ml-1 rounded bg-gray-100 px-1.5 py-0.5 text-xs dark:bg-gray-800"
|
||||
>{{ . }}</code
|
||||
>
|
||||
</div>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{- range $api.servers }}
|
||||
<div>
|
||||
<span class="font-medium text-gray-500 dark:text-gray-400"
|
||||
>Base URL</span
|
||||
>
|
||||
<code
|
||||
class="ml-1 rounded bg-gray-100 px-1.5 py-0.5 text-xs text-blue-600 dark:bg-gray-800 dark:text-blue-400"
|
||||
>{{ .url }}</code
|
||||
>
|
||||
</div>
|
||||
{{- end }}
|
||||
<a
|
||||
href="{{ $spec.Permalink }}"
|
||||
class="ml-auto text-blue-600 hover:underline dark:text-blue-400"
|
||||
>Download OpenAPI specification</a
|
||||
>
|
||||
</div>
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Overview ─────────────────────────────────────────────────────────── */}}
|
||||
{{ define "api-ref-overview" }}
|
||||
{{- $api := . -}}
|
||||
{{- with $api.info }}
|
||||
{{- with .description }}
|
||||
<section class="mb-10">
|
||||
<div class="prose dark:prose-invert max-w-none">
|
||||
{{ . | markdownify }}
|
||||
</div>
|
||||
</section>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Authentication ───────────────────────────────────────────────────── */}}
|
||||
{{ define "api-ref-auth" }}
|
||||
{{- $api := . -}}
|
||||
{{- with $api.components }}
|
||||
{{- with .securitySchemes }}
|
||||
<section class="mb-12">
|
||||
<h2
|
||||
id="authentication"
|
||||
class="mb-4 scroll-mt-24 text-2xl font-semibold"
|
||||
>
|
||||
Authentication
|
||||
</h2>
|
||||
{{- range $name, $scheme := . }}
|
||||
<div class="mb-4 flex flex-wrap items-center gap-x-4 gap-y-1 text-sm">
|
||||
<code
|
||||
class="rounded bg-gray-100 px-1.5 py-0.5 text-xs dark:bg-gray-800"
|
||||
>{{ $name }}</code
|
||||
>
|
||||
{{- with $scheme.type }}
|
||||
<span class="text-gray-500 dark:text-gray-400"
|
||||
>type: <code class="text-xs">{{ . }}</code></span
|
||||
>
|
||||
{{- end }}
|
||||
{{- with $scheme.scheme }}
|
||||
<span class="text-gray-500 dark:text-gray-400"
|
||||
>scheme: <code class="text-xs">{{ . }}</code></span
|
||||
>
|
||||
{{- end }}
|
||||
{{- with $scheme.bearerFormat }}
|
||||
<span class="text-gray-500 dark:text-gray-400"
|
||||
>bearer format: <code class="text-xs">{{ . }}</code></span
|
||||
>
|
||||
{{- end }}
|
||||
</div>
|
||||
{{- with $scheme.description }}
|
||||
<div class="prose dark:prose-invert max-w-none">
|
||||
{{ . | markdownify }}
|
||||
</div>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
</section>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Endpoints grouped by tag ─────────────────────────────────────────── */}}
|
||||
{{ define "api-ref-tags" }}
|
||||
{{- $api := . -}}
|
||||
{{- $paths := $api.paths -}}
|
||||
{{- $methods := slice "get" "post" "put" "patch" "delete" -}}
|
||||
{{- range $api.tags }}
|
||||
{{- $tagName := .name -}}
|
||||
<section class="mb-14">
|
||||
<h2
|
||||
id="tag-{{ $tagName | urlize }}"
|
||||
class="mb-1 scroll-mt-24 text-2xl font-semibold"
|
||||
>
|
||||
{{ $tagName | title }}
|
||||
</h2>
|
||||
{{- with .description }}
|
||||
<p class="mb-6 text-sm text-gray-500 dark:text-gray-400">{{ . }}</p>
|
||||
{{- end }}
|
||||
|
||||
{{- range $path, $item := $paths }}
|
||||
{{/* Resolve shared (path-level) parameters once. */}}
|
||||
{{- $sharedParams := slice -}}
|
||||
{{- with index $item "parameters" -}}
|
||||
{{- range . -}}
|
||||
{{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}}
|
||||
{{- $sharedParams = $sharedParams | append $p -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- range $methods -}}
|
||||
{{- $method := . -}}
|
||||
{{- with index $item $method -}}
|
||||
{{- $op := . -}}
|
||||
{{- if in $op.tags $tagName -}}
|
||||
{{ template "api-ref-operation" (dict
|
||||
"api" $api
|
||||
"op" $op
|
||||
"method" $method
|
||||
"path" $path
|
||||
"sharedParams" $sharedParams
|
||||
)
|
||||
}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end }}
|
||||
</section>
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Single operation card ────────────────────────────────────────────── */}}
|
||||
{{ define "api-ref-operation" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $op := .op -}}
|
||||
{{- $method := .method -}}
|
||||
{{- $path := .path -}}
|
||||
{{- $sharedParams := .sharedParams -}}
|
||||
|
||||
{{- $methodColors := dict
|
||||
"get" "bg-blue-100 text-blue-800 dark:bg-blue-900/40 dark:text-blue-300"
|
||||
"post" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300"
|
||||
"put" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300"
|
||||
"patch" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300"
|
||||
"delete" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300"
|
||||
-}}
|
||||
|
||||
{{- $anchor := "" -}}
|
||||
{{- with $op.operationId -}}
|
||||
{{- $anchor = printf "operation-%s" . -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- $curl := partial "api-ref/curl.html" (dict
|
||||
"api" $api
|
||||
"op" $op
|
||||
"method" $method
|
||||
"path" $path
|
||||
"sharedParams" $sharedParams
|
||||
)
|
||||
-}}
|
||||
|
||||
|
||||
<div
|
||||
{{ with $anchor }}id="{{ . }}"{{ end }}
|
||||
class="mb-8 scroll-mt-24 overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700"
|
||||
>
|
||||
<div
|
||||
class="flex flex-wrap items-center gap-3 border-b border-gray-200 bg-gray-50 px-4 py-3 dark:border-gray-700 dark:bg-gray-900"
|
||||
>
|
||||
<span
|
||||
class="{{ index $methodColors $method }} inline-block rounded px-2 py-0.5 font-mono text-xs font-bold uppercase"
|
||||
>{{ upper $method }}</span
|
||||
>
|
||||
<code class="font-mono text-sm">{{ $path }}</code>
|
||||
<div class="ml-auto flex items-center gap-3">
|
||||
{{- with $op.summary }}
|
||||
<span class="text-sm font-medium text-gray-700 dark:text-gray-300"
|
||||
>{{ . }}</span
|
||||
>
|
||||
{{- end }}
|
||||
<button
|
||||
x-data="{ copied: false }"
|
||||
@click="navigator.clipboard.writeText({{ $curl | jsonify }}).then(() => { copied = true; setTimeout(() => copied = false, 2000) })"
|
||||
:title="copied ? 'Copied!' : 'Copy as cURL'"
|
||||
class="inline-flex cursor-pointer items-center gap-1 rounded border border-gray-200 bg-white px-2 py-1 text-xs font-medium text-gray-700 transition-colors hover:bg-gray-50 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
|
||||
>
|
||||
<span class="icon-svg icon-sm" x-show="!copied" x-cloak>
|
||||
{{ partialCached "icon" "document-duplicate" "document-duplicate" }}
|
||||
</span>
|
||||
<span
|
||||
class="icon-svg icon-sm text-green-600 dark:text-green-400"
|
||||
x-show="copied"
|
||||
x-cloak
|
||||
>
|
||||
{{ partialCached "icon" "check-circle" "check-circle" }}
|
||||
</span>
|
||||
<span x-text="copied ? 'Copied' : 'cURL'"></span>
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="p-5">
|
||||
{{- with $op.description }}
|
||||
<div class="prose dark:prose-invert prose-sm mb-5 max-w-none">
|
||||
{{ . | markdownify }}
|
||||
</div>
|
||||
{{- end }}
|
||||
|
||||
{{ template "api-ref-params" (dict
|
||||
"api" $api
|
||||
"op" $op
|
||||
"sharedParams" $sharedParams
|
||||
)
|
||||
}}
|
||||
|
||||
{{ template "api-ref-body" (dict "api" $api "op" $op) }}
|
||||
|
||||
{{ template "api-ref-responses" (dict "api" $api "op" $op) }}
|
||||
</div>
|
||||
</div>
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Parameters table (path + operation; in: path/query/header) ───────── */}}
|
||||
{{ define "api-ref-params" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $op := .op -}}
|
||||
{{- $params := .sharedParams -}}
|
||||
{{- with index $op "parameters" -}}
|
||||
{{- range . -}}
|
||||
{{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}}
|
||||
{{- $params = $params | append $p -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- if $params }}
|
||||
<div class="mb-5">
|
||||
<h4
|
||||
class="mb-2 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400"
|
||||
>
|
||||
Parameters
|
||||
</h4>
|
||||
<table class="w-full border-collapse text-sm">
|
||||
<thead>
|
||||
<tr class="border-b border-gray-200 dark:border-gray-700">
|
||||
<th
|
||||
class="w-36 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Name
|
||||
</th>
|
||||
<th
|
||||
class="w-16 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
In
|
||||
</th>
|
||||
<th
|
||||
class="w-20 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Type
|
||||
</th>
|
||||
<th
|
||||
class="w-20 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Required
|
||||
</th>
|
||||
<th
|
||||
class="py-1.5 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Description
|
||||
</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{- range $params }}
|
||||
<tr
|
||||
class="border-b border-gray-100 last:border-0 dark:border-gray-800"
|
||||
>
|
||||
<td class="py-1.5 pr-4 align-top">
|
||||
<code class="rounded bg-gray-100 px-1 text-xs dark:bg-gray-800"
|
||||
>{{ .name }}</code
|
||||
>
|
||||
</td>
|
||||
<td
|
||||
class="py-1.5 pr-4 align-top text-xs text-gray-500 dark:text-gray-400"
|
||||
>
|
||||
{{ .in }}
|
||||
</td>
|
||||
<td
|
||||
class="py-1.5 pr-4 align-top font-mono text-xs text-gray-500 dark:text-gray-400"
|
||||
>
|
||||
{{ template "api-ref-type" (dict "api" $api "schema" .schema) }}
|
||||
</td>
|
||||
<td
|
||||
class="py-1.5 pr-4 align-top text-xs text-gray-500 dark:text-gray-400"
|
||||
>
|
||||
{{ if .required }}yes{{ else }}no{{ end }}
|
||||
</td>
|
||||
<td
|
||||
class="py-1.5 align-top text-sm text-gray-600 dark:text-gray-400"
|
||||
>
|
||||
{{ with .description }}{{ . | markdownify }}{{ end }}
|
||||
</td>
|
||||
</tr>
|
||||
{{- end }}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Request body ─────────────────────────────────────────────────────── */}}
|
||||
{{ define "api-ref-body" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $op := .op -}}
|
||||
{{- with $op.requestBody }}
|
||||
{{- $body := partial "api-ref/resolve.html" (dict "api" $api "node" .) }}
|
||||
<div class="mb-5">
|
||||
<h4
|
||||
class="mb-2 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400"
|
||||
>
|
||||
Request body
|
||||
</h4>
|
||||
{{- with $body.description }}
|
||||
<p class="mb-2 text-sm text-gray-600 dark:text-gray-400">
|
||||
{{ . | markdownify }}
|
||||
</p>
|
||||
{{- end }}
|
||||
{{- $ct := "" -}}
|
||||
{{- $media := dict -}}
|
||||
{{- range $name, $m := $body.content -}}
|
||||
{{- if not $ct -}}{{- $ct = $name -}}{{- $media = $m -}}{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if $ct }}
|
||||
<p class="mb-2 text-xs text-gray-500 dark:text-gray-400">
|
||||
Content type:
|
||||
<code class="rounded bg-gray-100 px-1 dark:bg-gray-800"
|
||||
>{{ $ct }}</code
|
||||
>
|
||||
</p>
|
||||
{{ template "api-ref-schema-link" (dict "api" $api "schema" $media.schema) }}
|
||||
{{ template "api-ref-examples" (dict
|
||||
"examples" $media.examples
|
||||
"prefix" "req"
|
||||
)
|
||||
}}
|
||||
{{- end }}
|
||||
</div>
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Responses ────────────────────────────────────────────────────────── */}}
|
||||
{{ define "api-ref-responses" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $op := .op -}}
|
||||
{{- $statusColors := dict
|
||||
"200" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300"
|
||||
"201" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300"
|
||||
"204" "bg-green-100 text-green-800 dark:bg-green-900/40 dark:text-green-300"
|
||||
"400" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300"
|
||||
"401" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300"
|
||||
"403" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300"
|
||||
"404" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300"
|
||||
"409" "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/40 dark:text-yellow-300"
|
||||
"500" "bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300"
|
||||
-}}
|
||||
{{- with $op.responses }}
|
||||
<div>
|
||||
<h4
|
||||
class="mb-2 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400"
|
||||
>
|
||||
Responses
|
||||
</h4>
|
||||
<div class="space-y-2">
|
||||
{{- range $code, $resp := . }}
|
||||
{{- $r := partial "api-ref/resolve.html" (dict "api" $api "node" $resp) }}
|
||||
<details
|
||||
{{ if hasPrefix $code "2" }}open{{ end }}
|
||||
class="group rounded border border-gray-200 dark:border-gray-700"
|
||||
>
|
||||
<summary
|
||||
class="flex cursor-pointer list-none items-center gap-2 rounded-t bg-gray-50 px-3 py-2 dark:bg-gray-900 [&::-webkit-details-marker]:hidden"
|
||||
>
|
||||
<span
|
||||
class="inline-block text-gray-400 transition-transform group-open:rotate-90 dark:text-gray-500"
|
||||
>▸</span
|
||||
>
|
||||
<span
|
||||
class="{{ index $statusColors $code | default "bg-gray-100 text-gray-700 dark:bg-gray-800 dark:text-gray-300" }} inline-block rounded px-1.5 py-0.5 font-mono text-xs font-semibold"
|
||||
>{{ $code }}</span
|
||||
>
|
||||
<span class="text-sm text-gray-600 dark:text-gray-400"
|
||||
>{{ $r.description }}</span
|
||||
>
|
||||
</summary>
|
||||
{{- $ct := "" -}}
|
||||
{{- $media := dict -}}
|
||||
{{- range $name, $m := $r.content -}}
|
||||
{{- if not $ct -}}
|
||||
{{- $ct = $name -}}{{- $media = $m -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- if $ct }}
|
||||
<div class="px-3 pt-2 pb-3">
|
||||
{{ template "api-ref-schema-link" (dict "api" $api "schema" $media.schema) }}
|
||||
{{ template "api-ref-examples" (dict
|
||||
"examples" $media.examples
|
||||
"prefix" (printf "resp-%s" $code)
|
||||
)
|
||||
}}
|
||||
</div>
|
||||
{{- end }}
|
||||
</details>
|
||||
{{- end }}
|
||||
</div>
|
||||
</div>
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Example block with optional tabs ─────────────────────────────────── */}}
|
||||
{{ define "api-ref-examples" }}
|
||||
{{- $examples := .examples -}}
|
||||
{{- $prefix := .prefix -}}
|
||||
{{- $tabs := slice -}}
|
||||
{{- range $name, $ex := $examples -}}
|
||||
{{- $tabs = $tabs | append (dict "name" $name "ex" $ex) -}}
|
||||
{{- end -}}
|
||||
{{- if $tabs }}
|
||||
{{- $first := (index $tabs 0).name -}}
|
||||
<div
|
||||
{{ if gt (len $tabs) 1 }}x-data="{ tab: {{ $first | jsonify }} }"{{ end }}
|
||||
>
|
||||
{{- if gt (len $tabs) 1 }}
|
||||
<div class="mb-2 flex flex-wrap gap-1">
|
||||
{{- range $tabs }}
|
||||
{{- $label := .name -}}
|
||||
{{- with .ex.summary }}{{ $label = . }}{{ end -}}
|
||||
<button
|
||||
@click="tab = {{ .name | jsonify }}"
|
||||
:class="tab === {{ .name | jsonify }} ? 'bg-blue-100 text-blue-800 dark:bg-blue-900/40 dark:text-blue-300' : 'bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400'"
|
||||
class="rounded px-2 py-0.5 text-xs font-medium"
|
||||
>
|
||||
{{ $label }}
|
||||
</button>
|
||||
{{- end }}
|
||||
</div>
|
||||
{{- end }}
|
||||
{{- range $tabs }}
|
||||
<div
|
||||
{{ if gt (len $tabs) 1 }}
|
||||
x-show="tab === {{ .name | jsonify }}"
|
||||
{{ end }}
|
||||
>
|
||||
{{- with .ex.value -}}
|
||||
<div
|
||||
class="syntax-light dark:syntax-dark not-prose overflow-hidden rounded border border-gray-200 dark:border-gray-700"
|
||||
>
|
||||
{{ highlight (. | jsonify (dict "indent" " ")) "json" "" }}
|
||||
</div>
|
||||
{{- end }}
|
||||
</div>
|
||||
{{- end }}
|
||||
</div>
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Inline schema-reference link (used in body/response) ─────────────── */}}
|
||||
{{ define "api-ref-schema-link" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $schema := .schema -}}
|
||||
{{- if reflect.IsMap $schema -}}
|
||||
{{- with index $schema "$ref" -}}
|
||||
{{- $parts := split . "/" -}}
|
||||
{{- $name := index $parts (sub (len $parts) 1) -}}
|
||||
<p class="mb-2 text-xs text-gray-500 dark:text-gray-400">
|
||||
Schema:
|
||||
<a
|
||||
href="#schema-{{ $name | urlize }}"
|
||||
class="font-mono text-blue-600 hover:underline dark:text-blue-400"
|
||||
>{{ $name }}</a
|
||||
>
|
||||
</p>
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Type rendering for parameter / property tables ───────────────────── */}}
|
||||
{{ define "api-ref-type" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $schema := .schema -}}
|
||||
{{- if not (reflect.IsMap $schema) -}}
|
||||
—
|
||||
{{- else -}}
|
||||
{{- with index $schema "$ref" -}}
|
||||
{{- $parts := split . "/" -}}
|
||||
{{- $name := index $parts (sub (len $parts) 1) -}}
|
||||
<a
|
||||
href="#schema-{{ $name | urlize }}"
|
||||
class="text-blue-600 hover:underline dark:text-blue-400"
|
||||
>{{ $name }}</a
|
||||
>
|
||||
{{- else -}}
|
||||
{{- with $schema.type -}}
|
||||
{{- if eq . "array" -}}
|
||||
array<{{ template "api-ref-type" (dict "api" $api "schema" $schema.items) }}>
|
||||
{{- else -}}
|
||||
{{ . }}
|
||||
{{- end -}}
|
||||
{{- else -}}
|
||||
{{- if $schema.allOf -}}
|
||||
object
|
||||
{{- else if $schema.anyOf -}}
|
||||
any
|
||||
{{- else if $schema.oneOf -}}
|
||||
any
|
||||
{{- else -}}
|
||||
—
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Schemas section ──────────────────────────────────────────────────── */}}
|
||||
{{ define "api-ref-schemas" }}
|
||||
{{- $api := . -}}
|
||||
{{- with $api.components -}}
|
||||
{{- with .schemas }}
|
||||
<section class="mb-12">
|
||||
<h2 id="schemas" class="mb-6 scroll-mt-24 text-2xl font-semibold">
|
||||
Schemas
|
||||
</h2>
|
||||
{{- range $name, $schema := . }}
|
||||
<div
|
||||
id="schema-{{ $name | urlize }}"
|
||||
class="mb-8 scroll-mt-24 rounded border border-gray-200 p-4 dark:border-gray-700"
|
||||
>
|
||||
<h3 class="mb-1 font-mono text-base font-semibold">{{ $name }}</h3>
|
||||
{{- with $schema.description }}
|
||||
<div
|
||||
class="prose dark:prose-invert prose-sm mb-3 max-w-none text-sm"
|
||||
>
|
||||
{{ . | markdownify }}
|
||||
</div>
|
||||
{{- end }}
|
||||
{{- with $schema.enum }}
|
||||
<p class="mb-3 text-sm text-gray-500 dark:text-gray-400">
|
||||
Enum:
|
||||
{{- range $i, $v := . -}}
|
||||
{{- if $i }},{{ end -}}
|
||||
<code
|
||||
class="rounded bg-gray-100 px-1 text-xs dark:bg-gray-800"
|
||||
>{{ $v }}</code
|
||||
>
|
||||
{{- end -}}
|
||||
</p>
|
||||
{{- end }}
|
||||
{{- with $schema.properties }}
|
||||
{{ template "api-ref-properties" (dict
|
||||
"api" $api
|
||||
"schema" $schema
|
||||
)
|
||||
}}
|
||||
{{- else }}
|
||||
{{- with $schema.items }}
|
||||
<p class="text-sm text-gray-500 dark:text-gray-400">
|
||||
Items:
|
||||
<span class="font-mono"
|
||||
>{{ template "api-ref-type" (dict "api" $api "schema" .) }}</span
|
||||
>
|
||||
</p>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
</div>
|
||||
{{- end }}
|
||||
</section>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
|
||||
{{/* ── Property table for a schema ──────────────────────────────────────── */}}
|
||||
{{ define "api-ref-properties" }}
|
||||
{{- $api := .api -}}
|
||||
{{- $schema := .schema -}}
|
||||
{{- $required := $schema.required | default slice -}}
|
||||
<table class="w-full border-collapse text-sm">
|
||||
<thead>
|
||||
<tr class="border-b border-gray-200 dark:border-gray-700">
|
||||
<th
|
||||
class="w-40 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Property
|
||||
</th>
|
||||
<th
|
||||
class="w-32 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Type
|
||||
</th>
|
||||
<th
|
||||
class="w-20 py-1.5 pr-4 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Required
|
||||
</th>
|
||||
<th
|
||||
class="py-1.5 text-left font-medium text-gray-700 dark:text-gray-300"
|
||||
>
|
||||
Description
|
||||
</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{- range $propName, $prop := $schema.properties }}
|
||||
<tr class="border-b border-gray-100 last:border-0 dark:border-gray-800">
|
||||
<td class="py-1.5 pr-4 align-top">
|
||||
<code class="rounded bg-gray-100 px-1 text-xs dark:bg-gray-800"
|
||||
>{{ $propName }}</code
|
||||
>
|
||||
</td>
|
||||
<td
|
||||
class="py-1.5 pr-4 align-top font-mono text-xs text-gray-500 dark:text-gray-400"
|
||||
>
|
||||
{{ template "api-ref-type" (dict "api" $api "schema" $prop) }}
|
||||
</td>
|
||||
<td
|
||||
class="py-1.5 pr-4 align-top text-xs text-gray-500 dark:text-gray-400"
|
||||
>
|
||||
{{ if in $required $propName }}yes{{ else }}no{{ end }}
|
||||
</td>
|
||||
<td class="py-1.5 align-top text-sm text-gray-600 dark:text-gray-400">
|
||||
{{- $resolved := partial "api-ref/resolve.html" (dict "api" $api "node" $prop) -}}
|
||||
{{- with $resolved.description -}}
|
||||
{{ . | markdownify }}
|
||||
{{- end -}}
|
||||
</td>
|
||||
</tr>
|
||||
{{- end }}
|
||||
</tbody>
|
||||
</table>
|
||||
{{ end }}
|
||||
@@ -1,185 +0,0 @@
|
||||
{{- /*
|
||||
Markdown rendering of an OpenAPI reference page.
|
||||
|
||||
Mirrors the HTML api-reference layout: unmarshals the colocated YAML
|
||||
Page Resource into a plain Hugo map and walks the spec to produce a
|
||||
flat markdown document. Used by the "View Markdown" / "Copy Markdown"
|
||||
actions and the .md alternate link.
|
||||
*/ -}}
|
||||
{{- $specRes := .Resources.GetMatch "*.yaml" -}}
|
||||
{{- $api := $specRes | transform.Unmarshal -}}
|
||||
{{- $methods := slice "get" "post" "put" "patch" "delete" -}}
|
||||
{{- $paths := $api.paths -}}
|
||||
# {{ .Title }}
|
||||
|
||||
{{ with .Description }}{{ . }}{{ end }}
|
||||
|
||||
{{ with $api.info }}
|
||||
{{- with .version }}- **Version**: `{{ . }}`
|
||||
{{ end -}}
|
||||
{{ end -}}
|
||||
{{- range $api.servers }}- **Base URL**: `{{ .url }}`
|
||||
{{ end }}
|
||||
- **OpenAPI specification**: [`{{ path.Base $specRes.RelPermalink }}`]({{ $specRes.Permalink }})
|
||||
|
||||
{{ with $api.info }}{{ with .description }}{{ . }}{{ end }}{{ end }}
|
||||
|
||||
{{ with $api.components }}{{ with .securitySchemes }}
|
||||
## Authentication
|
||||
|
||||
{{ range $name, $scheme := . }}
|
||||
**`{{ $name }}`**{{ with $scheme.type }} — type: `{{ . }}`{{ end }}{{ with $scheme.scheme }}, scheme: `{{ . }}`{{ end }}{{ with $scheme.bearerFormat }}, bearer format: `{{ . }}`{{ end }}
|
||||
|
||||
{{ with $scheme.description }}{{ . }}{{ end }}
|
||||
{{ end -}}
|
||||
{{ end }}{{ end }}
|
||||
|
||||
{{- range $api.tags }}
|
||||
## {{ .name | title }}
|
||||
|
||||
{{ with .description }}{{ . }}{{ end }}
|
||||
|
||||
{{- $tagName := .name -}}
|
||||
{{- range $path, $item := $paths -}}
|
||||
{{- $sharedParams := slice -}}
|
||||
{{- with index $item "parameters" -}}
|
||||
{{- range . -}}
|
||||
{{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}}
|
||||
{{- $sharedParams = $sharedParams | append $p -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- range $methods -}}
|
||||
{{- $method := . -}}
|
||||
{{- with index $item $method -}}
|
||||
{{- $op := . -}}
|
||||
{{- if in $op.tags $tagName }}
|
||||
### `{{ upper $method }}` `{{ $path }}`
|
||||
|
||||
{{ with $op.summary }}**{{ . }}**{{ end }}
|
||||
|
||||
{{ with $op.description }}{{ . }}{{ end }}
|
||||
|
||||
{{- $params := $sharedParams -}}
|
||||
{{- with index $op "parameters" -}}
|
||||
{{- range . -}}
|
||||
{{- $p := partial "api-ref/resolve.html" (dict "api" $api "node" .) -}}
|
||||
{{- $params = $params | append $p -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{ if $params }}
|
||||
**Parameters**
|
||||
|
||||
{{ range $params -}}
|
||||
- `{{ .name }}` ({{ .in }}{{ with .schema }}{{ with .type }}, {{ . }}{{ end }}{{ end }}{{ if .required }}, required{{ end }}){{ with .description }} — {{ . | strings.TrimSpace }}{{ end }}
|
||||
{{ end }}
|
||||
{{- end }}
|
||||
|
||||
{{- with $op.requestBody -}}
|
||||
{{- $body := partial "api-ref/resolve.html" (dict "api" $api "node" .) }}
|
||||
**Request body**{{ with $body.description }} — {{ . | strings.TrimSpace }}{{ end }}
|
||||
|
||||
{{- $ct := "" -}}
|
||||
{{- $media := dict -}}
|
||||
{{- range $n, $m := $body.content -}}
|
||||
{{- if not $ct -}}{{- $ct = $n -}}{{- $media = $m -}}{{- end -}}
|
||||
{{- end -}}
|
||||
{{ if $ct }}
|
||||
Content type: `{{ $ct }}`
|
||||
|
||||
{{ template "api-ref-md-schema-link" (dict "schema" $media.schema) }}
|
||||
{{ range $exName, $ex := $media.examples }}{{ with $ex.value }}
|
||||
```json
|
||||
{{ . | jsonify (dict "indent" " ") }}
|
||||
```
|
||||
{{ end }}{{ end }}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{- with $op.responses }}
|
||||
**Responses**
|
||||
|
||||
{{ range $code, $resp := . -}}
|
||||
{{- $r := partial "api-ref/resolve.html" (dict "api" $api "node" $resp) }}
|
||||
`{{ $code }}` — {{ with $r.description }}{{ . | strings.TrimSpace }}{{ end }}
|
||||
{{- $ct := "" -}}
|
||||
{{- $media := dict -}}
|
||||
{{- range $n, $m := $r.content -}}
|
||||
{{- if not $ct -}}{{- $ct = $n -}}{{- $media = $m -}}{{- end -}}
|
||||
{{- end }}
|
||||
{{ if $ct }}
|
||||
{{ template "api-ref-md-schema-link" (dict "schema" $media.schema) }}
|
||||
{{ range $exName, $ex := $media.examples }}{{ with $ex.value }}
|
||||
```json
|
||||
{{ . | jsonify (dict "indent" " ") }}
|
||||
```
|
||||
{{ end }}{{ end }}
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
{{ end -}}
|
||||
|
||||
{{ end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
|
||||
{{- with $api.components }}{{ with .schemas }}
|
||||
## Schemas
|
||||
|
||||
{{ range $name, $schema := . }}
|
||||
### `{{ $name }}`
|
||||
|
||||
{{ with $schema.description }}{{ . | strings.TrimSpace }}{{ end }}
|
||||
|
||||
{{ with $schema.enum -}}
|
||||
Enum: {{ range $i, $v := . }}{{ if $i }}, {{ end }}`{{ $v }}`{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{- with $schema.properties }}
|
||||
{{- $required := $schema.required | default slice }}
|
||||
| Property | Type | Required | Description |
|
||||
| -------- | ---- | -------- | ----------- |
|
||||
{{ range $propName, $prop := . -}}
|
||||
| `{{ $propName }}` | {{ template "api-ref-md-type" $prop }} | {{ if in $required $propName }}yes{{ else }}no{{ end }} | {{ with $prop.description }}{{ . | strings.TrimSpace | strings.ReplaceRE "\\s*\\n\\s*" " " }}{{ end }} |
|
||||
{{ end }}
|
||||
{{ end -}}
|
||||
|
||||
{{ end -}}
|
||||
{{ end }}{{ end }}
|
||||
|
||||
{{- /* ── Helpers ───────────────────────────────────────────────────────── */ -}}
|
||||
|
||||
{{- define "api-ref-md-type" -}}
|
||||
{{- $s := . -}}
|
||||
{{- if reflect.IsMap $s -}}
|
||||
{{- with index $s "$ref" -}}
|
||||
{{- $parts := split . "/" -}}
|
||||
{{- $name := index $parts (sub (len $parts) 1) -}}
|
||||
`{{ $name }}`
|
||||
{{- else -}}
|
||||
{{- with $s.type -}}
|
||||
{{- if eq . "array" -}}
|
||||
`array<`{{ template "api-ref-md-type" $s.items }}`>`
|
||||
{{- else -}}
|
||||
`{{ . }}`
|
||||
{{- end -}}
|
||||
{{- else -}}
|
||||
{{- if $s.allOf -}}`object`
|
||||
{{- else if or $s.anyOf $s.oneOf -}}`any`
|
||||
{{- else -}}—{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- else -}}—{{- end -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- define "api-ref-md-schema-link" -}}
|
||||
{{- $schema := .schema -}}
|
||||
{{- $indent := .indent | default "" -}}
|
||||
{{- if reflect.IsMap $schema -}}
|
||||
{{- with index $schema "$ref" -}}
|
||||
{{- $parts := split . "/" -}}
|
||||
{{- $name := index $parts (sub (len $parts) 1) -}}
|
||||
{{ $indent }}Schema: `{{ $name }}`
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
{{- end -}}
|
||||
Reference in new issue
Block a user