diff --git a/docs/content/1.docs/2.features/open-api.md b/docs/content/1.docs/2.features/open-api.md index 0d5876af..b87f37d5 100644 --- 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 index d21ed94c..b9466c26 100644 --- 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 index ab809106..9416e4a0 100644 --- 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 index f668b66d..6e3d10d8 100644 --- 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` + } + }) }) }