69 lines
3.1 KiB
HTML
69 lines
3.1 KiB
HTML
{{/*
|
|
Security Schemes Display
|
|
|
|
Renders OpenAPI security schemes as human-readable documentation.
|
|
Extracts securitySchemes from the referenced OpenAPI spec file.
|
|
|
|
Design principles:
|
|
- Each scheme gets an h2 heading (appears in "On this page" TOC)
|
|
- Focus on human-readable descriptions, not OpenAPI schema details
|
|
- Technical details (type, scheme, in) are omitted - they're for machines
|
|
- Descriptions should include usage examples
|
|
|
|
Required page params:
|
|
- staticFilePath: Path to the OpenAPI specification file
|
|
*/}}
|
|
|
|
{{ $specPath := .Params.staticFilePath }}
|
|
{{ if $specPath }}
|
|
{{/* Load the OpenAPI spec file from static directory */}}
|
|
{{ $fullPath := printf "static%s" $specPath }}
|
|
{{ $specContent := readFile $fullPath }}
|
|
{{ if $specContent }}
|
|
{{ $spec := transform.Unmarshal $specContent }}
|
|
{{ with $spec.components.securitySchemes }}
|
|
<section class="api-security-schemes">
|
|
{{ range $name, $scheme := . }}
|
|
<article class="security-scheme">
|
|
{{/* Human-friendly title from scheme name */}}
|
|
{{ $title := $name }}
|
|
{{/* Convert common scheme names to readable titles */}}
|
|
{{/* Short names (v1 specs) */}}
|
|
{{ if eq $name "BasicAuth" }}{{ $title = "Basic Authentication" }}{{ end }}
|
|
{{ if eq $name "TokenAuth" }}{{ $title = "Token Authentication" }}{{ end }}
|
|
{{ if eq $name "QueryAuth" }}{{ $title = "Query String Authentication" }}{{ end }}
|
|
{{ if eq $name "BearerAuth" }}{{ $title = "Bearer Token Authentication" }}{{ end }}
|
|
{{ if eq $name "ApiKeyAuth" }}{{ $title = "API Key Authentication" }}{{ end }}
|
|
{{/* Long names (v2+ specs) */}}
|
|
{{ if eq $name "BasicAuthentication" }}{{ $title = "Basic Authentication" }}{{ end }}
|
|
{{ if eq $name "TokenAuthentication" }}{{ $title = "Token Authentication" }}{{ end }}
|
|
{{ if eq $name "QuerystringAuthentication" }}{{ $title = "Query String Authentication" }}{{ end }}
|
|
|
|
<h2 id="{{ $name | urlize }}-authentication">{{ $title }}</h2>
|
|
|
|
{{/* Description is the primary content - should include usage examples */}}
|
|
{{ with $scheme.description }}
|
|
<div class="scheme-description">
|
|
{{ . | markdownify }}
|
|
</div>
|
|
{{ else }}
|
|
{{/* Fallback descriptions when OpenAPI spec doesn't provide one */}}
|
|
<div class="scheme-description">
|
|
{{ if eq $scheme.type "http" }}
|
|
{{ if eq $scheme.scheme "basic" }}
|
|
<p>Use HTTP Basic Authentication by including your credentials in the request.</p>
|
|
{{ else if eq $scheme.scheme "bearer" }}
|
|
<p>Include a bearer token in the <code>Authorization</code> header.</p>
|
|
{{ end }}
|
|
{{ else if eq $scheme.type "apiKey" }}
|
|
<p>Pass your API key {{ if eq $scheme.in "header" }}in the <code>{{ $scheme.name }}</code> header{{ else if eq $scheme.in "query" }}as the <code>{{ $scheme.name }}</code> query parameter{{ end }}.</p>
|
|
{{ end }}
|
|
</div>
|
|
{{ end }}
|
|
</article>
|
|
{{ end }}
|
|
</section>
|
|
{{ end }}
|
|
{{ end }}
|
|
{{ end }}
|