feat(openAPI): allow hiding routes

docs/1.guide/2.routing.md

@@ -206,6 +206,7 @@ You can define route handler meta at build-time using `defineRouteMeta` macro in
 
 ```ts [server/api/test.ts]
 defineRouteMeta({
+  openAPIEnabled: false, // defaults to true
   openAPI: {
     tags: ["test"],
     description: "Test route description",
@@ -294,6 +295,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' },
@@ -310,6 +312,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

@@ -381,6 +381,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

@@ -11,6 +11,7 @@ import { joinURL } from "ufo";
 import { defu } from "defu";
 import { handlersMeta } from "#nitro-internal-virtual/server-handlers-meta";
 import { useRuntimeConfig } from "../config";
+import { getRouteRulesForPath } from "../route-rules";
 
 // Served as /_openapi.json
 export default eventHandler((event) => {
@@ -63,6 +64,12 @@ function getHandlersMeta(): {
   let globals: OpenAPIGlobals = {};
 
   for (const h of handlersMeta) {
+    const enabledInRouteMeta = h.meta && h.meta.openAPIEnabled;
+    const enabledInRouteRules =
+      h.route && getRouteRulesForPath(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

@@ -13,6 +13,7 @@ export interface NitroRouteMeta {
   openAPI?: OperationObject & {
     $global?: Pick<OpenAPI3, "components"> & Extensable;
   };
+  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;