nitrojs · pi0 · Aug 22, 2024 · Jun 28, 2024 · Jun 28, 2024 · Jun 28, 2024
@@ -3,18 +3,58 @@ import type { NitroOptions } from "nitropack/types";
 import { join } from "pathe";
 
 export async function resolveOpenAPIOptions(options: NitroOptions) {
-  if (options.dev && options.experimental.openAPI) {
-    options.handlers.push({
-      route: "/_nitro/openapi.json",
-      handler: join(runtimeDir, "internal/routes/openapi"),
-    });
+  // Check if the experimental.openAPI option is enabled
+  if (!options.experimental.openAPI) {
+    return;
+  }
+
+  // Only enable for dev and (opt-in) production
+  if (!options.dev && !options.openAPI?.production) {
+    return;
+  }
+
+  const shouldPrerender =
+    !options.dev && options.openAPI?.production === "prerender";
+
+  const handlersEnv = shouldPrerender ? "prerender" : "";
+
+  const prerenderRoutes: string[] = [];
+
+  // Add openapi json route
+  const jsonRoute = options.openAPI?.route || "/_openapi.json";
+  prerenderRoutes.push(jsonRoute);
+  options.handlers.push({
+    route: jsonRoute,
+    env: handlersEnv,
+    handler: join(runtimeDir, "internal/routes/openapi"),
+  });
+
+  // Scalar UI
+  if (options.openAPI?.ui?.scalar !== false) {
+    const scalarRoute = options.openAPI?.ui?.scalar?.route || "/_scalar";
+    prerenderRoutes.push(scalarRoute);
     options.handlers.push({
-      route: "/_nitro/scalar",
+      route: options.openAPI?.ui?.scalar?.route || "/_scalar",
+      env: handlersEnv,
       handler: join(runtimeDir, "internal/routes/scalar"),
     });
+  }
+
+  // Swagger UI
+  if (options.openAPI?.ui?.swagger !== false) {
+    const swaggerRoute = options.openAPI?.ui?.swagger?.route || "/_swagger";
+    prerenderRoutes.push(swaggerRoute);
     options.handlers.push({
-      route: "/_nitro/swagger",
+      route: swaggerRoute,
+      env: handlersEnv,
       handler: join(runtimeDir, "internal/routes/swagger"),
     });
   }
+
+  // Prerender
+  if (shouldPrerender) {
+    options.prerender ??= {} as any;
+    options.prerender.routes ??= [];
+    options.prerender.routes.push(...prerenderRoutes);
+  }
 }
@@ -10,7 +10,7 @@ import { joinURL } from "ufo";
 import { handlersMeta } from "#nitro-internal-virtual/server-handlers-meta";
 import { useRuntimeConfig } from "../config";
 
-// Served as /_nitro/openapi.json
+// Served as /_openapi.json
 export default eventHandler((event) => {
   const runtimeConfig = useRuntimeConfig(event);
 

@@ -2,37 +2,39 @@ import type { ReferenceConfiguration } from "@scalar/api-reference";
 import { eventHandler } from "h3";
 import { useRuntimeConfig } from "../config";
 
-// Served as /_nitro/scalar
+// Served as /_scalar
 export default eventHandler((event) => {
   const runtimeConfig = useRuntimeConfig(event);
+  const title = runtimeConfig.nitro.openAPI?.meta?.title || "API Reference";
+  const description = runtimeConfig.nitro.openAPI?.meta?.description || "";
+  const openAPIEndpoint =
+    runtimeConfig.nitro.openAPI?.route || "./_openapi.json";
 
   // https://github.com/scalar/scalar
-  const configuration: ReferenceConfiguration = {
-    ...runtimeConfig.nitro.openAPI?.ui?.scalar,
-    spec: {
-      url: "/_nitro/openapi.json",
-      ...runtimeConfig.nitro.openAPI?.ui?.scalar?.spec,
-    },
+  const _config = runtimeConfig.nitro.openAPI?.ui
+    ?.scalar as ReferenceConfiguration;
+  const scalarConfig: ReferenceConfiguration = {
+    ..._config,
+    spec: { url: openAPIEndpoint, ..._config?.spec },
   };
 
   // The default page title
-  const title = "Nitro Scalar API Reference";
 
   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}" />
+        <meta name="description" content="${description}" />
         <title>${title}</title>
         <style>
-          ${configuration.theme ? null : customTheme}
+          ${scalarConfig.theme ? null : customTheme}
         </style>
       </head>
       <body>
         <script
           id="api-reference"
-          data-configuration="${JSON.stringify(configuration)
+          data-configuration="${JSON.stringify(scalarConfig)
             .split('"')
             .join("&quot;")}"
         ></script>

@@ -1,17 +1,23 @@
+import type { ReferenceConfiguration } from "@scalar/api-reference";
 import { eventHandler } from "h3";
+import { useRuntimeConfig } from "../config";
 
 // https://github.com/swagger-api/swagger-ui
 
-// Served as /_nitro/swagger
 export default eventHandler((event) => {
-  const title = "Nitro Swagger UI";
+  const runtimeConfig = useRuntimeConfig(event);
+  const title = runtimeConfig.nitro.openAPI?.meta?.title || "API Reference";
+  const description = runtimeConfig.nitro.openAPI?.meta?.description || "";
+  const openAPIEndpoint =
+    runtimeConfig.nitro.openAPI?.route || "./_openapi.json";
+
   const CDN_BASE = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@^5";
   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}" />
+        <meta name="description" content="${description}" />
         <title>${title}</title>
         <link rel="stylesheet" href="${CDN_BASE}/swagger-ui.css" />
       </head>
@@ -25,7 +31,7 @@ export default eventHandler((event) => {
         <script>
           window.onload = () => {
             window.ui = SwaggerUIBundle({
-              url: "./openapi.json",
+              url: ${JSON.stringify(openAPIEndpoint)},
               dom_id: "#swagger-ui",
               presets: [
                 SwaggerUIBundle.presets.apis,

@@ -1,5 +1,4 @@
 import type { RollupCommonJSOptions } from "@rollup/plugin-commonjs";
-import type { ReferenceConfiguration } from "@scalar/api-reference";
 import type { C12InputConfig, ConfigWatcher, ResolvedConfig } from "c12";
 import type { WatchConfigOptions } from "c12";
 import type { WatchOptions } from "chokidar";
@@ -33,6 +32,7 @@ import type {
 import type { NitroHooks } from "./hooks";
 import type { NitroModuleInput } from "./module";
 import type { NitroFrameworkInfo } from "./nitro";
+import type { NitroOpenAPIConfig } from "./openapi";
 import type { NitroPreset } from "./preset";
 import type { EsbuildOptions, NodeExternalsOptions } from "./rollup";
 import type { RollupConfig } from "./rollup";
@@ -92,16 +92,7 @@ export interface NitroOptions extends PresetOptions {
    * @see https://github.com/unjs/unwasm
    */
   wasm?: UnwasmPluginOptions;
-  openAPI?: {
-    meta?: {
-      title?: string;
-      description?: string;
-      version?: string;
-    };
-    ui?: {
-      scalar?: ReferenceConfiguration;
-    };
-  };
+  openAPI?: NitroOpenAPIConfig;
   experimental: {
     legacyExternals?: boolean;
     openAPI?: boolean;
@@ -359,7 +350,7 @@ export interface NitroRuntimeConfig extends NitroTypeskRuntimeConfig {
     routeRules?: {
       [path: string]: NitroRouteConfig;
     };
-    openAPI?: NitroOptions["openAPI"];
+    openAPI?: NitroOpenAPIConfig;
   };
   [key: string]: any;
 }
@@ -0,0 +1,59 @@
+import type { ReferenceConfiguration as ScalarConfig } from "@scalar/api-reference";
+
+/**
+ * Nitro OpenAPI configuration
+ */
+export interface NitroOpenAPIConfig {
+  /**
+   * OpenAPI meta information
+   */
+  meta?: {
+    title?: string;
+    description?: string;
+    version?: string;
+  };
+
+  /**
+   * OpenAPI json route
+   *
+   * Default is `/_openapi.json`
+   */
+  route?: string;
+
+  /**
+   * Enable OpenAPI generation for production builds
+   */
+  production?: false | "runtime" | "prerender";
+
+  /**
+   * UI configurations
+   */
+  ui?: {
+    /**
+     * Scalar UI configuration
+     */
+    scalar?:
+      | false
+      | (ScalarConfig & {
+          /**
+           * Scalar UI route
+           *
+           * Default is `/_scalar`
+           */
+          route?: string;
+        });
+    /**
+     * Swagger UI configuration
+     */
+    swagger?:
+      | false
+      | {
+          /**
+           * Swagger UI route
+           *
+           * Default is `/_swagger`
+           */
+          route?: string;
+        };
+  };
+}
@@ -118,6 +118,7 @@ export default defineNitroConfig({
     },
   },
   openAPI: {
+    production: "prerender",
     meta: {
       title: "Nitro Test Fixture",
       description: "Nitro Test Fixture API",

@@ -124,6 +124,14 @@ describe(
               "rewrite": "/api/hey/index.html",
               "route": "/api/hey",
             },
+            {
+              "rewrite": "/_swagger/index.html",
+              "route": "/_swagger",
+            },
+            {
+              "rewrite": "/_scalar/index.html",
+              "route": "/_scalar",
+            },
             {
               "rewrite": "/prerender/index.html",
               "route": "/prerender",

@@ -41,11 +41,18 @@ describe.skipIf(isWindows)("nitro:preset:cloudflare-pages", async () => {
           "/blog/static/*",
           "/cf-pages-exclude/*",
           "/build/*",
+          "/_openapi.json",
+          "/_openapi.json.br",
+          "/_openapi.json.gz",
+          "/_scalar",
+          "/_swagger",
           "/_unignored.txt",
           "/favicon.ico",
           "/json-string",
           "/prerender",
           "/prerender-custom",
+          "/_swagger/index.html.br",
+          "/_swagger/index.html.gz",
           "/api/hello",
           "/api/hey",
           "/prerender/index.html.br",

@@ -25,9 +25,8 @@ describe.skipIf(isCI)("nitro:preset:nitro-dev", async () => {
 
       describe("openAPI", () => {
         let spec: OpenAPI3;
-        it("/_nitro/openapi.json", async () => {
-          spec = ((await callHandler({ url: "/_nitro/openapi.json" })) as any)
-            .data;
+        it("/_openapi.json", async () => {
+          spec = ((await callHandler({ url: "/_openapi.json" })) as any).data;
           expect(spec.openapi).to.match(/^3\.\d+\.\d+$/);
           expect(spec.info.title).toBe("Nitro Test Fixture");
           expect(spec.info.description).toBe("Nitro Test Fixture API");

@@ -25,6 +25,12 @@ describe("nitro:preset:vercel", async () => {
         expect(config).toMatchInlineSnapshot(`
           {
             "overrides": {
+              "_scalar/index.html": {
+                "path": "_scalar",
+              },
+              "_swagger/index.html": {
+                "path": "_swagger",
+              },
               "api/hey/index.html": {
                 "path": "api/hey",
               },