Documenting Endpoints

Basic Endpoint Documentation

Document individual API endpoints with detailed information:

import { YelixHono, openapi } from '@yelix/hono';
import { zValidatorYelix } from '@yelix/zod-validator';
import { z } from 'zod';

const app = new YelixHono();

app.get(
  '/users/:id',
  openapi({
    summary: 'Get User by ID',
    description: 'Retrieves a user by their unique ID.',
    tags: ['User'],
  }),
  zValidatorYelix(
    'param',
    z.object({
      id: z.string(),
    })
  ),
  (c) => {
    const { id } = c.req.valid('param' as never) as { id: string };
    return c.json({ id, name: 'John Doe', email: 'johndoe@example.com' });
  }
);

Documentation Options

The openapi() middleware accepts several options:

• summary: Short description of what the endpoint does
• description: Longer explanation of the endpoint’s functionality
• tags: Groups related endpoints together in the documentation
• hide: Set to true to hide the endpoint from documentation (useful for internal endpoints)
• path: Override the path shown in documentation
• method: Override the HTTP method shown in documentation

Request Validation

Use zValidatorYelix to validate and document request parameters:

import { zValidatorYelix } from '@yelix/zod-validator';
import { z } from 'zod';

// Validate path parameters
app.get(
  '/users/:id',
  zValidatorYelix('param', z.object({ id: z.string().uuid() })),
  (c) => { /* ... */ }
);

// Validate query parameters
app.get(
  '/users',
  zValidatorYelix('query', z.object({
    page: z.string().transform(Number).pipe(z.number().int().positive()),
    limit: z.string().transform(Number).pipe(z.number().int().positive())
  })),
  (c) => { /* ... */ }
);

// Validate request body
app.post(
  '/users',
  zValidatorYelix('json', z.object({
    name: z.string().min(1),
    email: z.email(),
  })),
  (c) => { /* ... */ }
);

Response Documentation

Document response structures using zodToResponseSchema:

import { YelixHono, openapi, zodToResponseSchema } from '@yelix/hono';
import { z } from 'zod';

app.get(
  '/users/:id',
  openapi({
    summary: 'Get User by ID',
    responses: {
      200: {
        description: 'User retrieved successfully',
        content: zodToResponseSchema(
          z.object({
            id: z.uuid(),
            name: z.string(),
            email: z.email(),
          })
        ),
      },
      404: {
        description: 'User not found',
        content: zodToResponseSchema(
          z.object({
            error: z.string(),
            message: z.string(),
          })
        ),
      },
    },
  }),
  (c) => { /* ... */ }
);

Learn more about Response Schemas.

Using Tags

Tags help organize endpoints in your documentation:

app.get('/users', openapi({ tags: ['User'] }), handler);
app.post('/users', openapi({ tags: ['User'] }), handler);
app.get('/posts', openapi({ tags: ['Post'] }), handler);
app.post('/posts', openapi({ tags: ['Post'] }), handler);

All endpoints with the same tag will be grouped together in the documentation.

Next Steps

• Learn about Response Schemas
• See Complete Examples