api-layout

content/features/api.md

@@ -0,0 +1,6 @@
+---
+title: API Layout
+reference: "exampleApi"
+layout: api
+hidden: true
+---

content/features/full.md

@@ -0,0 +1,5 @@
+---
+title: All Docs as One Page
+layout: full
+description: one page to rule them all
+---

hugo.yaml

@@ -31,8 +31,6 @@ outputs:
   home: [ "HTML", "JSON"]
   page: [ "HTML", "JSON"]
   section: [ "HTML", "JSON"]
-  list: [ "HTML", "JSON"]
-  taxonomies: [ "HTML", "JSON"]
 
 # Theme Feature Settings
 params: 

layouts/_default/api.html

@@ -0,0 +1,20 @@
+{{- define "main" }}
+{{- $reference := .Page.Params.reference -}}
+{{- range $data, $reference := .Site.Data}}
+{{- with $reference}}
+<div class="container mx-auto p-4 text-black">
+    <!-- API Information Card -->
+    <div class="p-4 border border-gray-200 rounded mb-4">
+        <h2>{{ .info.title }}</h2>
+        <p>{{ $.Page.RenderString .info.description }}</p>
+        <p><strong>Version:</strong> {{ .info.version }}</p>
+    </div>
+    <!-- Endpoints List -->
+
+    {{- partial "api/endpoints.html" . }}
+    <!-- Components -->
+    {{- partial "api/components.html" .components.schemas }}  
+</div>
+{{- end}}
+{{- end}}
+{{- end }}

layouts/_default/full.html

@@ -0,0 +1,7 @@
+{{ define "main" }}
+    {{- range .Site.Pages}}
+    <div id="articleContent" class="p-4 text-black">
+        {{ .Content }}
+    </div>
+    {{- end}}
+{{ end }}

layouts/partials/api/component.html

@@ -0,0 +1,18 @@
+{{- $schemaName := .schemaName }}
+{{- $schema := .schema }}
+{{- $nested := .nested }}
+<div id="{{$schemaName | lower}}-schema" class="{{if $nested}}{{else}}bg-zinc-100{{end}} p-2 rounded text-sm space-y-2">
+    <h6>{{ $schemaName }}</h6>
+    <div id="{{$schemaName | lower}}-properties" class="space-y-2">
+        {{- with $schema }}
+        {{- range $propertyName, $propertyDetails := .properties }}
+        <div id="{{$schemaName | lower }}-{{$propertyName}}-property" class="space-y-2">
+        <span class="font-thin">{{ $propertyName }}</span>
+        <!-- type & format -->
+        <code class="text-xs p-1 rounded">{{ $propertyDetails.type }}</code> <span class="text-xs">{{- with $propertyDetails.format}}({{.}}){{- else}}{{- end }}</span>
+        <p>{{- with $propertyDetails.description}}{{.}}{{- else}}{{- end }}</p>
+        </div>
+        {{- end }}
+        {{- end }}
+    </div>
+</div>

layouts/partials/api/components.html

@@ -0,0 +1,8 @@
+{{- $components := . }}
+<div id="components" class="flex flex-col w-full mb-4 space-y-4">
+    <h2>Components</h2>
+    {{- range $schemaName, $schema := $components }}
+    {{$componentContext := dict "schemaName" $schemaName "schema" $schema "nested" false}}
+        {{- partial "api/component.html" $componentContext}}
+    {{- end}}
+</div>

layouts/partials/api/endpoints.html

@@ -0,0 +1,17 @@
+{{/*  Endpoints expects a context that includes:
+    - info: the info to the OpenAPI spec
+    - paths: the paths object from the OpenAPI spec
+    - components: the components object from the OpenAPI spec
+    - security: the security object from the OpenAPI spec
+    - servers: the servers object from the OpenAPI spec
+*/}}
+{{$reference := . }}
+<div class="flex flex-col">
+    {{- range $path, $methods := .paths }}
+        <div class="my-4">
+        <h2>{{$path}}</h2>
+        {{- $context := dict "reference" $reference "path" $path "methods" $methods }}
+        {{- partial "api/methods.html" $context }}
+        </div>
+    {{- end }}
+</div>

layouts/partials/api/method.html

@@ -0,0 +1,34 @@
+{{/*  Method expects a context with:
+    - .reference: a reference to the whole api spec
+    - .path: the path of the endpoint these methods belong to
+    - .method: the method that belongs to the path
+    - .details: the details of the method
+*/}}
+
+{{$reference := .reference }}
+{{$path := .path }}
+{{$method := .method }}
+{{$details := .details }}
+
+{{- $bg := "" -}}
+{{- if eq .method "get" }}
+    {{- $bg = "bg-green-100" }}
+{{- else if eq .method "post" }}
+    {{- $bg = "bg-blue-100" }}
+{{- else if eq .method "put" }}
+    {{- $bg = "bg-yellow-100" }}
+{{- else if eq .method "delete" }}
+    {{- $bg = "bg-red-100" }}
+{{- end }}
+<div id="{{.path}}-{{.method}}-method" class="pl-2 space-y-2">
+    <div class="flex items-center space-x-2">
+        <div class="text-lg font-bold p-1 rounded {{$bg}}">{{ .method | upper }}</div>
+        <span class="font-thin">{{ .details.summary }}</span>
+    </div>
+    <p class="text-sm">{{.details.description | markdownify }}</p>
+
+    {{$context := dict "reference" $reference "path" $path "method" $method "details" $details }}
+    {{partial "api/security.html" $context }}
+    {{partial "api/parameters.html" $context }}
+    {{partial "api/responses.html" $context }}
+</div>

layouts/partials/api/methods.html

@@ -0,0 +1,15 @@
+{{/*  Methods expect a context with:
+    - .reference: a reference to the whole api spec
+    - .path: the path of the endpoint these methods belong to
+    - .methods: the methods that belong to the path   
+*/}}
+{{$reference := .reference}}
+{{$path := .path}}
+<div id="left-panel" class="flex flex-col w-1/2 mb-4 space-y-8">
+    {{- range $method, $details := .methods }}
+        {{- $context := dict "reference" $reference "path" $path "method" $method "details" $details }}
+        {{- partial "api/method.html" $context }}
+    {{- end }}
+</div>
+
+

layouts/partials/api/parameter.html

@@ -0,0 +1,26 @@
+{{/* api/parameter.html expects a context with:
+     - .parameter: The parameter object
+     - .parametersMap: A map of all parameters
+*/}}
+{{- $parameter := .parameter }}
+{{- $parametersMap := .parametersMap }}
+{{- if $parameter.name }}
+<!-- If the parameter is not a reference, we can use it directly -->
+    <li>
+        <span class="font-bold">{{ $parameter.name }}</span>
+        (<code class="p-1 rounded text-xs">{{ $parameter.in }}</code>):
+        <p>{{ $parameter.description | markdownify }}</p>
+    </li>
+{{- else }}
+<!-- If the parameter is a reference, we need to look it up in the map -->
+    {{- range $parameterName, $parameter := $parameter }}
+        {{ $path := strings.TrimPrefix "#/components/parameters/" . }}
+        {{- with (index $parametersMap $path) }}
+            <li>
+                <span class="font-bold">{{ .name }}</span>
+                (<code class="p-1 rounded text-xs">{{with .schema.type}}{{.}}{{end}} {{with .in}}- {{.}}{{end}}</code>) {{with .required}}<span class="bg-zinc-100 p-1 rounded">required</span>{{end}}
+                <p>{{ .description | markdownify }}</p>
+            </li>
+        {{- end }}
+    {{- end }}
+{{- end }}

layouts/partials/api/parameters.html

@@ -0,0 +1,22 @@
+{{/* api/parameters.html expects a context with:
+     - .reference: Reference object containing shared data
+     - .path: The API path
+     - .method: The HTTP method
+     - .details: Details about the method, including security info
+*/}}
+{{$reference := .reference }}
+{{$path := .path | anchorize}}
+{{$method := .method}}
+{{$details := .details}}
+{{- $parameters := .reference.components.parameters}}
+{{- with .details.parameters }}
+<h4>Parameters</h4>
+<div id="{{$path}}-{{$method}}-params" class="p-1 rounded text-sm">
+    <ul class="space-y-2">
+        {{- range . }}
+            {{- $context := dict "parameter" . "parametersMap" $parameters }}
+            {{- partial "api/parameter.html" $context }}
+        {{- end }}
+    </ul>
+</div>
+{{- end }}

layouts/partials/api/response.html

@@ -0,0 +1,85 @@
+{{/* api/response.html expects a context with:
+     - .reference: Reference object containing shared data
+     - .path: The API path
+     - .method: The HTTP method
+     - .statusCode: the HTTP status code
+    - .response: The response object
+*/}}
+{{- $reference := .reference }}
+{{- $path := .path }}
+{{- $method := .method }}
+{{- $statusCode := .statusCode }}
+{{- $response := .response }}
+{{- $schemas := .reference.components.schemas }}
+{{- $bg := "" }}
+{{- if or (eq $statusCode "200") (eq $statusCode "204") }}
+    {{- $bg = "bg-green-100" }}
+{{- else }}
+    {{- $bg = "bg-red-100" }}
+{{- end }}
+{{- with $response}}
+<div class="flex flex-col">
+    <div class="space-y-2">
+        <h5 class="{{$bg}} p-2 rounded">{{ $statusCode }} <span class="font-thin">{{- .description }}</span></h5>
+        {{- $appjson := index .content "application/json"}}
+        {{- range $refType, $responseItem := $appjson.schema }}
+        {{- if reflect.IsMap $responseItem }}
+            <!-- Handle case where $responseItem is a map of $refs -->
+        This is a map: {{.}}
+        {{else if reflect.IsSlice $responseItem}}
+        <!-- Handle case where $responseItem is a $ref '#/components/responses/...' -->
+        This is a slice: {{.}}
+        {{else }}
+        <!-- Handle case where $responseItem is a $ref '#/components/responses/...' -->
+        {{ $path := strings.TrimPrefix "#/components/schemas/" . }}
+        {{- with (index $schemas $path) }}
+        <div class="bg-blue-100 p-2 rounded">
+            {{if reflect.IsMap . }}
+            <p class="font-bold">{{.type}}</p>
+            <ul class="space-y-2">
+                {{- range $key, $schema := .properties }}
+                <!-- Likely reusable for map and slice once we get to .properties of each-->
+                <li class="space-y-1">
+                    <span class="font-medium">{{$key}}</span>
+                    {{with $schema }}
+                    {{- with .type}}
+                    <span class="font-thin">{{.}}</span>
+                    {{- end}}
+                    {{- with .format}}
+                    <span class="font-thin">({{.}})</span>
+                    {{- end}}
+                    <div class="pl-2 space-y-1">
+                        {{with .description}}
+                        <p class="text-sm">{{. | markdownify }}</p>
+                        {{end}}
+                        {{- with .example}}
+                        <p class="text-xs"><span class="font-bold">Examples:</span> {{.}}</p>
+                        {{- end}}
+                        {{- with .enum}}
+                        <p class="text-xs"><span class="font-bold">Enums:</span> {{.}}</p>
+                        {{- end}}
+                    </div>
+                    {{- end }}
+                    {{- $schemaRef := index $schema "$ref"}}
+                    <!-- loop becomes more obvious here; i think we need a template --> 
+                    {{ $path := strings.TrimPrefix "#/components/schemas/" $schemaRef }}
+                    {{- with (index $schemas $path) }}
+                    {{end}}
+
+                </li>
+                {{- end }}
+            </ul>
+            {{- else if reflect.IsSlice . }}
+            <!-- likey never used but here just in case -->
+            {{- else }}
+            <!-- likey never used but here just in case -->
+            {{- end }}
+        </div>
+        {{- end }}
+        {{- end }}
+        {{- end }}
+    </div>
+</div>
+{{- end}}
+
+

layouts/partials/api/responses.html

@@ -0,0 +1,20 @@
+{{/* api/security.html expects a context with:
+     - .reference: Reference object containing shared data
+     - .path: The API path
+     - .method: The HTTP method
+     - .details: Details about the method, including security info
+*/}}
+{{- $reference := .reference }}
+{{- $path := .path | anchorize }}
+{{- $method := .method}}
+{{- $details := .details }}
+
+{{- with $details.responses}}
+<h4>Responses</h4>
+<div id="{{$path}}-{{$method}}-responses" class="space-y-2">
+    {{- range $statusCode, $response := . }}
+        {{- $context := dict "reference" $reference "path" $path "method" $method "statusCode" $statusCode "response" $response }}
+        {{- partial "api/response.html" $context }}
+    {{- end }}
+</div>
+{{- end }}

layouts/partials/api/schema.html

@@ -0,0 +1,52 @@
+{{$schema := .schema}}
+{{$schemas := .schemas}}
+{{- with $schema }}
+<p class="font-bold">{{.type}}</p>
+    <ul class="space-y-2">
+        {{- range $key, $schema := .properties }}
+        <li class="space-y-1">
+            {{$context := dict "key" $key "schema" $schema "schemas" $schemas }}
+            {{ template "nestedSchemaDetails" $context }}
+            {{- range $i, $item := .items }}
+                {{- if reflect.IsMap $item }} 
+                <!-- Handle case where $item is a map of $refs -->
+                {{- $itemRef := index $item "$ref"}}
+                {{ $path := strings.TrimPrefix "#/components/schemas/" $itemRef }}
+                {{$context := dict "key" $key "schema" $item "schemas" $schemas}}
+                {{- else if reflect.IsSlice $item}}
+                xxxxx {{.}} <!-- example output: [map[$ref:#/components/schemas/saved_credit_card_view] map[$ref:#/components/schemas/saved_paypal_account_view]]-->
+                {{range . }}
+                {{- $itemRef := index . "$ref"}}
+                {{$itemRef}}
+                {{end}}
+                {{- else }}
+                123456 <div class="bg-red-100">{{.}}</div> <!-- example output: #/components/schemas/webhooks_type  -->
+                {{- end }}
+            {{- end }}
+        </li>
+        {{- end }}
+    </ul>
+{{- end }}
+{{- define "nestedSchemaDetails"}}
+<span class="font-medium">{{.key}}</span>
+{{- with .schema }}
+{{- with .type}}
+<span class="font-thin">{{.}}</span>
+{{- end}}
+{{- with .format}}
+<span class="font-thin">({{.}})</span>
+{{- end}}
+<div class="pl-2 space-y-1">
+    {{with .description}}
+    <p class="text-sm">{{. | markdownify }}</p>
+    {{end}}
+    {{- with .example}}
+    <p class="text-xs"><span class="font-bold">Examples:</span> {{.}}</p>
+    {{- end}}
+    {{- with .enum}}
+    <p class="text-xs"><span class="font-bold">Enums:</span> {{.}}</p>
+    {{- end}}
+</div>
+{{- end }}
+{{- end }}
+

layouts/partials/api/schemaTemplate.html

@@ -0,0 +1,26 @@
+{{- $schemas := .schemas -}}
+{{- $schema := .schema -}}
+
+{{- if reflect.IsMap $schema -}}
+<div class="bg-blue-100 p-2 rounded">
+    {{- if $schema.type }}
+    <p class="font-bold">{{ $schema.type }}</p>
+    {{- end }}
+    <ul class="space-y-2">
+        {{- range $key, $schemaItem := $schema.properties }}
+        <li class="space-y-1">
+            <span class="font-medium">{{ $key }}</span>
+            <!-- Here we call the same partial recursively for nested properties -->
+            {{- $nestedContext := dict "schema" $schemaItem "schemas" $schemas }}
+            {{- partial "api/schema-display.html" $nestedContext }}
+        </li>
+        {{- end }}
+    </ul>
+</div>
+{{- else if reflect.IsString $schema -}}
+    {{- $refPath := strings.TrimPrefix "#/components/schemas/" $schema }}
+    {{- with (index $schemas $refPath) }}
+        {{- $refContext := dict "schema" . "schemas" $schemas }}
+        {{- partial "api/schema-display.html" $refContext }}
+    {{- end }}
+{{- end }}