feat(openAPI): allow hiding routes

[horvbalint]

🔗 Linked issue

#2889

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR adds a new property openAPIEnabled to the NitroRouteMeta and NitroRouteConfig types. Using this property one can include/exclude specific routes in the generated _openapi.json.

To only include a part of the backend one can do for example:

export default defineNitroConfig({
  experimental: {
    openAPI: true,
  },
  routeRules: {
    "**": {
      openAPIEnabled: false,
    },
    "/api/public/**": {
      openAPIEnabled: true,
    },
  },
});

It is also possible to override this rule using the routes meta, like:

// /api/public/exceptionRoute.ts

defineRouteMeta({
  openAPIEnabled: false
})

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[horvbalint]

hey, @horvbalint what's the progress on this? I looked at the checks and the error don't seem to have anything to do with the additon of the property.

Hi, the PR is ready for review I think. The error in the checks dont seem to come from my changes, but I had no time to investigate it :/

[miantiao-me]

Expecting to be able to merge secondary PRs, a lot of the OpenAPI generated by the current code is not needed

[bitbytebit1]

I was also looking for this feature. In the mean time I achieved the same using a nitro plugin:

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook("beforeResponse", (event, { body }) => {
    if (event.path === "/openapi.json") {
      const entriesToDelete = [
        "/openapi.json",
        "/_docs/scalar",
        "/",
      ];
      entriesToDelete.forEach((entry) => {
        delete body.paths[entry];
      });
    }
  });
});

[vercel]

@pi0 is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitrojs/nitro/nitropack@2890

commit: c11303c

[vachmara]

My fully typed version adapted from @bitbytebit1 :

import { defineNitroPlugin, useRuntimeConfig } from 'nitropack/runtime'
import { createRouter, toRouteMatcher } from 'radix3'

declare module 'nitropack/types' {
  interface NitroOpenAPIConfig {
    allow?: string[]
  }
}

export default defineNitroPlugin((nitroApp) => {
  const openapi = useRuntimeConfig()?.nitro?.openAPI
  const endpoint = openapi?.route || '/_openapi.json'
  const allow: string[] = Array.isArray(openapi?.allow) ? openapi.allow : []

  const router = createRouter({
    routes: Object.fromEntries(allow.map(p => [p, { ok: true }]))
  })
  const matcher = toRouteMatcher(router)

  nitroApp.hooks.hook('beforeResponse', (event, response) => {
    const body = response.body as { paths?: Record<string, unknown> }
    if (event.path !== endpoint) return
    if (!body?.paths) return

    for (const p of Object.keys(body.paths)) {
      // If allowlist is empty => keep everything
      if (allow.length && matcher.matchAll(p).length === 0) {
        delete body.paths?.[p]
      }
    }
  })
})

Usage on nuxt.config.ts:

export default defineNuxtConfig({
  nitro: {
    openAPI: {
      allow: [
        '/api/**'
      ],
    }
  }
})