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.

Swagger is on in development and off in production unless you turn it on (see Swagger in production).

Quick startCopy Anchor Link

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.

Put a plugin route in the specCopy Anchor Link

There is no extra work. The route, module and plugin files that make a route reachable also make it documented. What you control is how good the documentation is. The steps below improve the GET /api/site-notes/notes/{id} route of the site-notes plugin.

Before you beginCopy Anchor Link

• The site-notes plugin with its notes module, from API modules and Database.

export const showNoteRoute = buildRoute({
  route: {
    method: 'get',
    path: '/{id}',
    description: 'Get one note by id', 
    request: {
      params: z.object({
        id: z.coerce.number().int().positive().openapi({ example: 1 }), 
      }),
    },
    // ...responses and handler stay as they are

export const notesModule = buildModule({
  name: 'notes',
  routes: [listNotesRoute, showNoteRoute],
  // ...
})

export const siteNotesApiPlugin = () =>
  buildApiPlugin({
    manifest,
    modules: [helloModule, notesModule],
    // ...
  })

Check the resultCopy Anchor Link

Let the plugin rebuild, restart the dev server and refresh /api/swagger. The restart matters, because the API builds the document on its first request and serves that copy from then on. The (Site Notes) - Notes group lists GET /api/site-notes/notes/{id} with the summary "Get one note by id" and 1 filled in as the example id. "Try it out" sends a real request with your cookies attached.

Where the spec comes fromCopy Anchor Link

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

GroupingCopy Anchor Link

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 (@vitnode/core reads Core, site-notes reads Site Notes), 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.

Swagger in productionCopy Anchor Link

VitNode serves /api/swagger and /api/swagger/doc when NODE_ENV is development and switches them off otherwise. The document names every route, parameter and response shape of the install, the admin tree included, and neither path checks a session. To publish it in production anyway, turn it on in the API config:

export const vitNodeApiConfig = buildApiConfig({
  // ...
  docs: { enabled: true }, 
})

docs: { enabled: false } turns it off in development too. If you enable it on a public install, put something in front of both paths, such as an allowlist at your reverse proxy. See Self-hosted.

GotchasCopy Anchor Link

RelatedCopy Anchor Link