feat: Add openAPIEnabled property to route metas and route rules

docs/1.guide/2.routing.md

@@ -205,13 +205,14 @@ Returning anything from a middleware will close the request and should be avoide
 
 ### Route Meta
 
-You can define route handler meta at build-time using `defineRouteMeta` micro in the event handler files.
+You can define route handler meta at build-time using `defineRouteMeta` macro in the event handler files.
 
 > [!IMPORTANT]
 > 🚧 This feature is currently experimental.
 
 ```ts [/api/test.ts]
 defineRouteMeta({
+  openAPIEnabled: false, // defaults to true
   openAPI: {
     tags: ["test"],
     description: "Test route description",
@@ -298,6 +299,7 @@ export default defineNitroConfig({
     '/blog/**': { cache: { /* cache options*/ } },
     '/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
     '/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
+    '/api/v1/admin/**': { openAPIEnabled: false },
     '/old-page': { redirect: '/new-page' },
     '/old-page/**': { redirect: '/new-page/**' },
     '/proxy/example': { proxy: 'https://example.com' },
@@ -314,6 +316,7 @@ export default defineNuxtConfig({
     '/blog/**': { cache: { /* cache options*/ } },
     '/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
     '/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
+    '/api/v1/admin/**': { openAPIEnabled: false },
     '/old-page': { redirect: '/new-page' },
     '/old-page/**': { redirect: '/new-page/**' },
     '/proxy/example': { proxy: 'https://example.com' },

docs/3.config/0.index.md

@@ -361,6 +361,7 @@ routeRules: {
   '/blog/**': { cache: { /* cache options*/ } },
   '/assets/**': { headers: { 'cache-control': 's-maxage=0' } },
   '/api/v1/**': { cors: true, headers: { 'access-control-allow-methods': 'GET' } },
+  '/api/v1/admin/**': { openAPIEnabled: false },
   '/old-page': { redirect: '/new-page' }, // uses status code 307 (Temporary Redirect)
   '/old-page2': { redirect: { to:'/new-page2', statusCode: 301 } },
   '/old-page/**': { redirect: '/new-page/**' },

src/runtime/internal/routes/openapi.ts

@@ -9,6 +9,9 @@ import type {
 import { joinURL } from "ufo";
 import { handlersMeta } from "#nitro-internal-virtual/server-handlers-meta";
 import { useRuntimeConfig } from "../config";
+import { createRouter as createRadixRouter, toRouteMatcher } from "radix3";
+import type { NitroRouteRules, NitroRuntimeConfig } from "nitropack/types";
+import defu from "defu";
 
 // Served as /_openapi.json
 export default eventHandler((event) => {
@@ -36,14 +39,27 @@ export default eventHandler((event) => {
         variables: {},
       },
     ],
-    paths: getPaths(),
+    paths: getPaths(runtimeConfig),
   };
 });
 
-function getPaths(): PathsObject {
+function getPaths(runtimeConfig: NitroRuntimeConfig): PathsObject {
   const paths: PathsObject = {};
 
+  const _routeRulesMatcher = toRouteMatcher(
+    createRadixRouter({ routes: runtimeConfig.nitro.routeRules })
+  );
+
+  const _getRouteRules = (path: string) =>
+    defu({}, ..._routeRulesMatcher.matchAll(path).reverse()) as NitroRouteRules;
+
   for (const h of handlersMeta) {
+    const enabledInRouteMeta = h.meta && h.meta.openAPIEnabled;
+    const enabledInRouteRules =
+      h.route && _getRouteRules(h.route).openAPIEnabled;
+    const openAPIEnabled = enabledInRouteMeta ?? enabledInRouteRules;
+    if (openAPIEnabled === false) continue;
+
     const { route, parameters } = normalizeRoute(h.route || "");
     const tags = defaultTags(h.route || "");
     const method = (h.method || "get").toLowerCase() as Lowercase<HTTPMethod>;

src/types/handler.ts

@@ -7,6 +7,7 @@ type MaybeArray<T> = T | T[];
 /** @exprerimental */
 export interface NitroRouteMeta {
   openAPI?: OperationObject;
+  openAPIEnabled?: boolean;
 }
 
 export interface NitroEventHandler {

src/types/route-rules.ts

@@ -11,6 +11,7 @@ export interface NitroRouteConfig {
   prerender?: boolean;
   proxy?: string | ({ to: string } & ProxyOptions);
   isr?: number /* expiration */ | boolean | VercelISRConfig;
+  openAPIEnabled?: boolean;
 
   // Shortcuts
   cors?: boolean;