Merge pull request #23944 from thaJeztah/api_crawlable

thaJeztah · web-flow · commit a5d29ea796d5 · 2026-01-08T17:04:53.000+01:00
api: include alternate link for swagger / OpenAPI spec
diff --git a/layouts/_default/api.html b/layouts/_default/api.html
@@ -1,14 +1,21 @@
 <!DOCTYPE html>
 <html lang="en">
-
 <head>
+  {{ $specURL := urls.Parse (printf "/%s%s.yaml" .File.Dir .File.ContentBaseName) }}
   <title>{{ .Title }}</title>
   <!-- needed for adaptive design -->
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="description" content="{{ .Description }}" />
   <meta charset="utf-8" />
   <!-- favicon -->
   <link rel="shortcut icon" href="/assets/images/favicon.svg" type="image/svg">
+  <!--
+  Provide a link to the swagger / OpenAPI spec itself. We're currently using
+  Swagger (OpenAPI v2) for some, so use a more generic "application/yaml" type.
+
+  Once all our specs are updated to OpenAPI v3, we can change this to "application/vnd.oai.openapi"
+  -->
+  <link rel="alternate" href="{{ $specURL.String | absURL }}" type="application/yaml" title="{{ .Title }} (Swagger/OpenAPI)" />
   <style>
     body {
       margin: 0;
@@ -49,7 +56,12 @@
 </head>
 
 <body>
-  {{ $specURL := urls.Parse (printf "/%s%s.yaml" .File.Dir .File.ContentBaseName) }}
+  <noscript>
+    <p>
+      This page is rendered with JavaScript.<br>
+      <a target="_blank" href="{{ $specURL.String | absURL }}" rel="noreferrer">Download {{ .Title }} Swagger/OpenAPI specification</a>
+    </p>
+  </noscript>
   {{ if or (strings.HasPrefix .RelPermalink "/reference/api/hub/") (strings.HasPrefix .RelPermalink "/reference/api/registry/") }}
     <redoc spec-url="{{ $specURL.String }}" suppress-warnings="true" lazy-rendering></redoc>
   {{ else }}
