k.tags

Declare the set of tags used to group routes across nested route trees and the OpenAPI spec.

Declare the tags routes are grouped under. Name the result under tags on defineConfig.

pnpm add kizunajs@beta

bun add kizunajs@beta

npm install kizunajs@beta

import { Kizuna } from 'kizunajs';

Parameters

k.tags(tags: Record<string, TagOptions | string>): TagSet

Each entry is keyed by an id you choose, and routes reference tags by these keys. A value is either a TagOptions object or a plain title string:

Option	Type	Required	Description
`title`	`string`	Yes	Tag name shown in OpenAPI
`description`	`string`	No	Description included in the OpenAPI tag definition
`externalDocs`	`object`	No	`{ url, description? }` external docs for the tag

Returns

A TagSet. Once your Config carries it, k.routes completes the group tag and a route's own tags, and the generated OpenAPI document lists each tag with its title and description.

Example

tags.ts

import { Kizuna } from 'kizunajs';

export const tags = k.tags({
    users: {
        title: 'Users',
        description: 'User management endpoints',
    },
    health: 'Health',
});

k.ts

import { defineConfig } from 'kizunajs';
import { tags } from './src/tags';
import { routes } from './src/routes';

export default defineConfig({
    tags,
    routes,
});

users.ts

import { k } from './k';

export const usersRoutes = k.routes('users', {
    listUsers: k
        .route({
            method: 'GET',
            path: '/users',
            responses: {
                200: z.object({
                    users: z.array(UserSchema),
                }),
            },
        })
        .handler(/* ... */),
});

Cross-tagging

Routes reference tags by key, with completion. A route can list more than one tag, which is useful for tagging it across groups:

users.ts

cancelAccount: k
    .route({
        method: 'POST',
        path: '/account/cancel',
        tags: ['users', 'health'],
        // ...
    })
    .handler(/* ... */),

See the Routes guide for the full nesting pattern.

Parameters

Returns

Example

Cross-tagging

On this page