feat: experimental /_nitro/openapi.json and /_nitro/swagger for …

…dev mode (#1162)

package.json

@@ -92,6 +92,7 @@
     "node-fetch-native": "^1.1.0",
     "ofetch": "^1.0.1",
     "ohash": "^1.1.1",
+    "openapi-typescript": "^6.2.1",
     "pathe": "^1.1.0",
     "perfect-debounce": "^0.1.3",
     "pkg-types": "^1.0.2",

src/options.ts

@@ -324,6 +324,18 @@ export async function loadOptions(
   // Resolve plugin paths
   options.plugins = options.plugins.map((p) => resolvePath(p, options));
 
+  // Add open-api endpoint
+  if (options.dev) {
+    options.handlers.push({
+      route: "/_nitro/openapi.json",
+      handler: "#internal/nitro/routes/openapi",
+    });
+    options.handlers.push({
+      route: "/_nitro/swagger",
+      handler: "#internal/nitro/routes/swagger",
+    });
+  }
+
   return options;
 }
 

src/rollup/plugins/handlers.ts

@@ -3,13 +3,16 @@ import type { Nitro, NitroRouteRules, NitroEventHandler } from "../../types";
 import { virtual } from "./virtual";
 
 export function handlers(nitro: Nitro) {
+  const getHandlers = () =>
+    [
+      ...nitro.scannedHandlers,
+      ...nitro.options.handlers,
+    ] as NitroEventHandler[];
+
   return virtual(
     {
       "#internal/nitro/virtual/server-handlers": () => {
-        const handlers: NitroEventHandler[] = [
-          ...nitro.scannedHandlers,
-          ...nitro.options.handlers,
-        ];
+        const handlers = getHandlers();
         if (nitro.options.serveStatic) {
           handlers.unshift({
             middleware: true,
@@ -38,6 +41,15 @@ export function handlers(nitro: Nitro) {
           handlers.filter((h) => h.lazy).map((h) => h.handler)
         );
 
+        const handlersMeta = getHandlers()
+          .filter((h) => h.route)
+          .map((h) => {
+            return {
+              route: h.route,
+              method: h.method,
+            };
+          });
+
         const code = `
 ${imports
   .map((handler) => `import ${getImportId(handler)} from '${handler}';`)
@@ -63,6 +75,8 @@ ${handlers
   )
   .join(",\n")}
 ];
+
+export const handlersMeta = ${JSON.stringify(handlersMeta, null, 2)}
   `.trim();
         return code;
       },

src/runtime/routes/openapi.ts

@@ -0,0 +1,69 @@
+import { eventHandler } from "h3";
+import type {
+  OpenAPI3,
+  PathItemObject,
+  OperationObject,
+  ParameterObject,
+} from "openapi-typescript";
+import { handlersMeta } from "#internal/nitro/virtual/server-handlers";
+
+// Served as /_nitro/openapi.json
+export default eventHandler((event) => {
+  return <OpenAPI3>{
+    openapi: "3.0.0",
+    info: {
+      title: "Nitro Server Routes",
+      version: null,
+    },
+    servers: [
+      {
+        url: "http://localhost:3000",
+        description: "Local Development Server",
+        variables: {},
+      },
+    ],
+    schemes: ["http"],
+    paths: {
+      ...Object.fromEntries(
+        handlersMeta.map((h) => {
+          const parameters: ParameterObject[] = [];
+
+          let anonymouseCtr = 0;
+          const route = h.route
+            .replace(/:(\w+)/g, (_, name) => `{${name}}`)
+            .replace(/\/(\*)\//g, () => `/{param${++anonymouseCtr}}/`)
+            .replace(/\*\*{/, "{")
+            .replace(/\/(\*\*)$/g, () => `/{*param${++anonymouseCtr}}`);
+
+          const paramMatches = route.matchAll(/{(\*?\w+)}/g);
+          for (const match of paramMatches) {
+            const name = match[1];
+            if (!parameters.some((p) => p.name === name)) {
+              parameters.push({ name, in: "path", required: true });
+            }
+          }
+
+          const tags: string[] = [];
+          if (route.startsWith("/api/")) {
+            tags.push("API Routes");
+          } else if (route.startsWith("/_")) {
+            tags.push("Internal");
+          } else {
+            tags.push("App Routes");
+          }
+
+          const item: PathItemObject = {
+            [(h.method || "get").toLowerCase()]: <OperationObject>{
+              tags,
+              parameters,
+              responses: {
+                200: { description: "OK" },
+              },
+            },
+          };
+          return [route, item];
+        })
+      ),
+    },
+  };
+});

src/runtime/routes/swagger.ts

@@ -0,0 +1,44 @@
+import { eventHandler } from "h3";
+
+// https://github.com/swagger-api/swagger-ui
+
+// Served as /_nitro/swagger
+export default eventHandler((event) => {
+  const title = "Nitro Swagger UI";
+  const CDN_BASE = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@^4";
+  return html`<!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="description" content="${title}" />
+        <title>${title}</title>
+        <link rel="stylesheet" href="${CDN_BASE}/swagger-ui.css" />
+      </head>
+      <body>
+        <div id="swagger-ui"></div>
+        <script src="${CDN_BASE}/swagger-ui-bundle.js" crossorigin></script>
+        <script
+          src="${CDN_BASE}/swagger-ui-standalone-preset.js"
+          crossorigin
+        ></script>
+        <script>
+          window.onload = () => {
+            window.ui = SwaggerUIBundle({
+              url: "./openapi.json",
+              dom_id: "#swagger-ui",
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset,
+              ],
+              layout2: "StandaloneLayout",
+            });
+          };
+        </script>
+      </body>
+    </html> `;
+});
+
+function html(str, ...args) {
+  return String.raw(str, ...args);
+}

src/runtime/virtual/server-handlers.d.ts

@@ -1,6 +1,6 @@
 import type { H3EventHandler, LazyEventHandler, RouterMethod } from "h3";
 
-type HandlerDefinition = {
+export type HandlerDefinition = {
   route: string;
   lazy?: boolean;
   middleware?: boolean;
@@ -12,3 +12,10 @@ type HandlerDefinition = {
 };
 
 export const handlers: HandlerDefinition[];
+
+export type HandlerMeta = {
+  route: string;
+  method?: RouterMethod;
+};
+
+export const handlersMeta: HandlerMeta[];

test/fixture/nitro.config.ts

@@ -11,6 +11,12 @@ export default defineNitroConfig({
       },
     ],
   },
+  handlers: [
+    {
+      route: "/api/test/*/foo",
+      handler: "~/api/hello.ts",
+    },
+  ],
   devProxy: {
     "/proxy/example": { target: "https://example.com", changeOrigin: true },
   },