feat: add Open API tab in Nuxt Devtools with Scalar

nuxt-hub · Jan 7, 2025 · 91d5016 · 91d5016
1 parent 53d375a
commit 91d5016
Show file tree

Hide file tree

Showing 4 changed files with 41 additions and 2 deletions.
diff --git a/docs/content/1.docs/2.features/open-api.md b/docs/content/1.docs/2.features/open-api.md
@@ -28,9 +28,26 @@ After you deploy your project, NuxtHub Admin will showcase your API documentatio
 
 :nuxt-img{src="/images/landing/nuxthub-admin-open-api.png" alt="Nuxt Open API Scalar integration" width="915" height="515" data-zoom-src="/images/landing/nuxthub-admin-open-api.png"}
 
+You can define route handler meta (at build time) using the `defineRouteMeta` macro:
+
+```ts [pages/api/ok.ts]
+defineRouteMeta({
+  openAPI: {
+    description: 'Test route description',
+    parameters: [{ in: "query", name: "test", required: true }],
+  },
+});
+
+export default defineEventHandler(() => "OK");
+```
+
+::note{to="https://swagger.io/specification/v3/"}
+See swagger specification for available OpenAPI options.
+::
+
 ## Nuxt DevTools
 
-In development, you can use Nuxt DevTools to access your API routes. using the `Server Routes` tab.
+In development, you can use Nuxt DevTools to access your API routes using the `Open API` or  `Server Routes` tabs.
 
 It list all the API routes in your project as well as providing a playground to send and test your endpoints.
 

diff --git a/playground/server/api/chat.post.ts b/playground/server/api/chat.post.ts
@@ -1,5 +1,12 @@
 import { AIStream, formatStreamPart } from 'ai'
 
+defineRouteMeta({
+  openAPI: {
+    description: 'Chat with AI.',
+    tags: ['ai']
+  }
+})
+
 export default defineEventHandler(async (event) => {
   const { messages } = await readBody(event)
 

diff --git a/src/features.ts b/src/features.ts
@@ -248,7 +248,11 @@ export function setupOpenAPI(nuxt: Nuxt, hub: HubConfig) {
   nuxt.options.nitro.openAPI.production ||= 'runtime'
   nuxt.options.nitro.openAPI.route ||= '/api/_hub/openapi.json'
   nuxt.options.nitro.openAPI.ui ||= {}
-  nuxt.options.nitro.openAPI.ui.scalar ||= false
+  if (nuxt.options.dev) {
+    nuxt.options.nitro.openAPI.ui.scalar = {
+      route: '/api/_hub/scalar'
+    }
+  }
   nuxt.options.nitro.openAPI.ui.swagger ||= false
   hub.openAPIRoute = nuxt.options.nitro.openAPI.route
   addServerScanDir(resolve('./runtime/openapi/server'))

diff --git a/src/utils/devtools.ts b/src/utils/devtools.ts
@@ -47,5 +47,16 @@ export function addDevToolsCustomTabs(nuxt: Nuxt, hub: HubConfig) {
         src: `https://admin.hub.nuxt.com/embed/cache?url=${url}`
       }
     })
+
+    hub.openAPIRoute && addCustomTab({
+      category: 'server',
+      name: 'hub-open-api',
+      title: 'OpenAPI',
+      icon: 'i-lucide-file-text',
+      view: {
+        type: 'iframe',
+        src: `/api/_hub/scalar`
+      }
+    })
   })
 }