feat(swagger): add link to show openapi spec

Author: sripwoud

.eslintignore

@@ -34,3 +34,5 @@ yarn-error.log*
 
 !apps/docs
 !apps/website/app/build
+
+apps/api/src/swagger-custom-ui.js

apps/api/package.json

@@ -33,7 +33,8 @@
         "siwe": "^1.1.6",
         "sqlite3": "^5.1.4",
         "typeorm": "^0.3.12",
-        "uuid": "^9.0.0"
+        "uuid": "^9.0.0",
+        "yaml": "^2.7.0"
     },
     "devDependencies": {
         "@nestjs/cli": "^9.0.0",

apps/api/src/main.ts

@@ -2,6 +2,9 @@ import { Logger, ValidationPipe } from "@nestjs/common"
 import { NestFactory } from "@nestjs/core"
 import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger"
 import { ironSession } from "iron-session/express"
+import { stringify } from "yaml"
+import { readFileSync } from "fs"
+import { join } from "path"
 import { AppModule } from "./app/app.module"
 import { GroupsService } from "./app/groups/groups.service"
 
@@ -51,80 +54,27 @@ async function bootstrap() {
 
     const document = SwaggerModule.createDocument(app, config)
 
+    const customJsStr = readFileSync(
+        join(__dirname, "swagger-custom-ui.js"),
+        "utf8"
+    )
+
     const configUI = {
         swaggerOptions: { defaultModelsExpandDepth: -1 },
         customfavIcon:
             "https://raw.githubusercontent.com/bandada-infra/bandada/main/apps/dashboard/src/assets/favicon.ico",
         customSiteTitle: "Bandada API Docs",
         customCss: `.topbar-wrapper img {content:url('https://raw.githubusercontent.com/bandada-infra/bandada/d5268274cbb93f73a1960e131bff0d2bf1eacea9/apps/dashboard/src/assets/icon1.svg'); width:60px; height:auto;}
         .swagger-ui .topbar { background-color: transparent; } small.version-stamp { display: none !important; }`,
-        customJsStr: `
-    // Add a custom title to the right side of the Swagger UI page
-    document.addEventListener('DOMContentLoaded', function() {
-        const customTitle = document.createElement('div');
-        customTitle.style.position = 'absolute';
-        customTitle.style.top = '27px';
-        customTitle.style.padding = '10px';
-        customTitle.style.color = 'black';
-        customTitle.style.fontSize = '18px';
-        customTitle.style.padding = '0 20px';
-        customTitle.style.maxWidth = '1460px';
-        customTitle.style.display = 'flex';
-        customTitle.style.justifyContent = 'end';
-        customTitle.style.width = '100%';
-
-
-        // Create a hyperlink element
-        const link = document.createElement('a');
-        link.href = 'https://github.com/bandada-infra/bandada';
-        link.rel = 'noreferrer noopener nofollow';
-        link.target = '_blank'
-        link.style.color = 'grey';
-        link.style.display = 'flex';
-
-        // Create a text node for the link text
-        const linkText = document.createTextNode('Github');
-
-        // Append the text node to the link
-        link.appendChild(linkText);
-
-        // Create an SVG element for the GitHub icon
-        const githubIcon = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
-        githubIcon.setAttribute('width', '24');
-        githubIcon.setAttribute('height', '24');
-        githubIcon.setAttribute('viewBox', '0 0 20 20');
-        githubIcon.setAttribute('fill', 'currentColor');
-
-        const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
-        path.setAttribute('d', 'M8 .153C3.589.153 0 3.742 0 8.153c0 3.436 2.223 6.358 5.307 7.408.387.071.53-.168.53-.374 0-.185-.007-.674-.01-1.322-2.039.445-2.47-.979-2.47-.979-.334-.849-.815-1.075-.815-1.075-.667-.457.05-.448.05-.448.739.052 1.13.76 1.13.76.656 1.124 1.719.799 2.134.61.067-.478.256-.8.466-.98-1.63-.184-3.34-.815-3.34-3.627 0-.8.287-1.457.754-1.969-.076-.185-.327-.932.072-1.943 0 0 .618-.198 2.03.752a6.74 6.74 0 0 1 1.8-.245c.61.003 1.226.082 1.8.245 1.41-.95 2.027-.752 2.027-.752.4 1.011.148 1.758.073 1.943.47.512.754 1.17.754 1.969 0 2.82-1.712 3.44-3.35 3.623.264.227.497.672.497 1.356 0 .977-.009 1.764-.009 2.004 0 .207.141.449.544.373C13.775 14.511 16 11.59 16 8.154 16 3.743 12.411 .154 8 .154z');
-
-        // Append the path to the GitHub icon
-        githubIcon.appendChild(path);
-
-        // Append the GitHub icon to the link
-        link.insertBefore(githubIcon, link.firstChild);
-
-        // Apply some padding to create space between the icon and the text
-        link.style.paddingLeft = '8px';
-
-        // Append the link to the custom title
-        customTitle.appendChild(link);
-
-        const parentDiv = document.createElement('div');
-        parentDiv.style.display = 'flex';
-        parentDiv.style.justifyContent = 'center';
-        parentDiv.style.width = 'auto';
-
-
-        parentDiv.appendChild(customTitle)
-
-        document.body.appendChild(parentDiv);
-    });
-`
+        customJsStr
     }
 
     SwaggerModule.setup("/", app, document, configUI)
 
+    app.getHttpAdapter().get("/openapi.yml", (req, res) => {
+        res.type("text/yaml").send(stringify(document))
+    })
+
     await app.listen(port)
 
     Logger.log(`🚀 Application is running on: http://localhost:${port}`)

apps/api/src/swagger-custom-ui.js

@@ -0,0 +1,93 @@
+document.addEventListener("DOMContentLoaded", function () {
+    const linkStyles = {
+        color: "grey",
+        textDecoration: "underline",
+        fontSize: "14px",
+        display: "flex",
+        alignItems: "center",
+        gap: "5px"
+    }
+
+    const linkAttributes = {
+        rel: "noreferrer noopener nofollow",
+        target: "_blank"
+    }
+
+    function El({ tag, id, href, text, attrs = {}, styles = {} }) {
+        const el = document.createElement(tag)
+        if (id) el.id = id
+        if (href) el.href = href
+        if (text) el.innerText = text
+        Object.entries(attrs).forEach(([key, value]) =>
+            el.setAttribute(key, value)
+        )
+        Object.assign(el.style, styles)
+        return el
+    }
+
+    const A = ({ id, href, text }) =>
+        El({
+            id,
+            href,
+            text,
+            tag: "a",
+            styles: linkStyles,
+            attrs: linkAttributes
+        })
+
+    function addCustomLinks() {
+        const topbar = document.querySelector(".topbar")
+        if (!topbar) return
+
+        if (document.getElementById("ghLink")) return
+
+        const customContainer = El({
+            tag: "div",
+            styles: {
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "end",
+                position: "absolute",
+                top: "20px",
+                right: "40px",
+                gap: "8px"
+            }
+        })
+
+        const ghLink = A({
+            id: "ghLink",
+            href: "https://github.com/bandada-infra/bandada",
+            text: ""
+        })
+
+        const githubIcon = document.createElement("span")
+        githubIcon.innerHTML = `
+        <svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 98 96"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#24292f"/></svg>
+        `
+        ghLink.prepend(githubIcon)
+
+        const yamlLink = A({
+            id: "yamlLink",
+            href: "/openapi.yml",
+            text: "openapi.yml"
+        })
+
+        customContainer.appendChild(ghLink)
+        customContainer.appendChild(yamlLink)
+        topbar.appendChild(customContainer)
+    }
+
+    // Handle late-loading Swagger UI
+    const observer = new MutationObserver((mutationsList, observer) => {
+        for (const mutation of mutationsList) {
+            if (mutation.type === "childList") {
+                addCustomLinks()
+            }
+        }
+    })
+
+    observer.observe(document.body, { childList: true, subtree: true })
+
+    // Run once in case .topbar is already present
+    addCustomLinks()
+})

apps/api/tsconfig.build.json

@@ -1,4 +1,5 @@
 {
     "extends": "./tsconfig.json",
-    "exclude": ["node_modules", "dist", "**/*spec.ts", "**/*.test.ts"]
+    "exclude": ["node_modules", "dist", "**/*spec.ts", "**/*.test.ts"],
+    "include": ["src", "types"]
 }

apps/api/tsconfig.json

@@ -17,6 +17,7 @@
         "noImplicitAny": false,
         "strictBindCallApply": false,
         "forceConsistentCasingInFileNames": false,
-        "noFallthroughCasesInSwitch": false
+        "noFallthroughCasesInSwitch": false,
+        "allowJs": true
     }
 }

yarn.lock

@@ -12206,6 +12206,7 @@ __metadata:
     typeorm: "npm:^0.3.12"
     typescript: "npm:^4.7.4"
     uuid: "npm:^9.0.0"
+    yaml: "npm:^2.7.0"
   languageName: unknown
   linkType: soft
 
@@ -32757,6 +32758,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yaml@npm:^2.7.0":
+  version: 2.7.0
+  resolution: "yaml@npm:2.7.0"
+  bin:
+    yaml: bin.mjs
+  checksum: 10/c8c314c62fbd49244a6a51b06482f6d495b37ab10fa685fcafa1bbaae7841b7233ee7d12cab087bcca5a0b28adc92868b6e437322276430c28d00f1c1732eeec
+  languageName: node
+  linkType: hard
+
 "yargs-parser@npm:13.1.2, yargs-parser@npm:^13.1.2":
   version: 13.1.2
   resolution: "yargs-parser@npm:13.1.2"