Swagger

VitNode's API is built on @hono/zod-openapi, so the Zod schemas a route declares are its documentation. Nothing is written twice and nothing can drift: if the schema changes, the spec changes, and the request that no longer matches it is rejected.

Quick start

Start the dev server and open Swagger UI in a browser:

Whichever origin serves /api/* serves the UI, because it is a route on the same Hono app. The raw document is one path deeper, at /api/swagger/doc - OpenAPI 3.0.0, titled VitNode API, versioned with the @vitnode/core release you have installed. Point any OpenAPI tool at that URL.

Every path reads /api/{pluginId}/{module}/{route}, which is why core's session endpoint is /api/@vitnode/core/users/session. That is not a Swagger convention - it is how the app is mounted, and Architecture walks the whole request path.

Where the spec comes from

You never register anything with Swagger. Four steps in the API's own build produce the document as a side effect:

Put a plugin route in the spec

There is no extra work - the same three files that make a route reachable make it documented. What you control is how good the documentation is.

import { z } from '@hono/zod-openapi'
import { buildRoute } from '@vitnode/core/api/lib/route'

import { CONFIG_PLUGIN } from '@/const'

export const showOrderRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: {
    method: 'get',
    path: '/{id}',
    description: 'Get one order by id', 
    request: {
      params: z.object({
        id: z.string().openapi({ example: '1' }), 
      }),
    },
    responses: {
      200: {
        content: {
          'application/json': {
            schema: z.object({ id: z.string(), total: z.number() }),
          },
        },
        description: 'The order',
      },
    },
  },
  handler: async (c) => c.json({ id: '1', total: 42 }),
})

import { buildModule } from '@vitnode/core/api/lib/module'

import { CONFIG_PLUGIN } from '@/const'
import { showOrderRoute } from './routes/show.route'

export const ordersModule = buildModule({
  pluginId: CONFIG_PLUGIN.pluginId,
  name: 'orders', 
  routes: [showOrderRoute], 
})

import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { ordersModule } from '@/api/modules/orders/orders.module'
import { CONFIG_PLUGIN } from '@/const'

export const shopApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    modules: [ordersModule], 
  })

Grouping

Swagger has exactly one grouping mechanism - the tag - so the tag carries both halves of "where does this endpoint live". The plugin comes from pluginId with its scope dropped and title-cased, the module from the name you gave buildModule:

buildModule({
  pluginId: '@vitnode/core', // (Core)
  name: 'users', // - Users
  routes: [sessionRoute],
})

A nested module is named after its whole chain, so (Core) - Admin / Users stays a separate group from the top-level (Core) - Users:

buildModule({
  pluginId: '@vitnode/core',
  name: 'admin',
  routes: [],
  modules: [usersAdminModule], // (Core) - Admin / Users
})

The chain matters because module names repeat across the tree - core has a users module and an admin/users one, plus cron, queue and files twice over. A leaf-only tag would merge the public and admin halves of each into one group.

Groups appear in the order the plugins declared their modules, with core first.

Gotchas

Next