Complete Examples

Basic Example

A simple API with OpenAPI documentation:

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

const app = new YelixHono();

// Basic configuration
app.__openapi.setTitle('My API Documentation');
app.__openapi.setDescription('A simple API example');

// Simple endpoint
app.get('/', openapi({
  summary: 'Get API information',
  description: 'Returns basic API information',
}), (c) => {
  return c.json({ message: 'Hello from Yelix API' });
});

// Expose OpenAPI JSON
app.get('/openapi.json', openapi({ hide: true }), (c) => {
  return c.json(app.getOpenAPI());
});

Deno.serve(app.fetch);

Full Featured Example

A complete example with all OpenAPI features:

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

const app = new YelixHono();

// 1. Basic configuration
app.__openapi.setTitle('User Management API');
app.__openapi.setDescription('API for managing users');

// 2. Server setup
app.__openapi.setServers([
  {
    url: 'http://localhost:8000',
    description: 'Local Server',
  },
  {
    url: 'https://api.example.com',
    description: 'Production Server',
  },
]);

// 3. Security schemas
app.__openapi.addSecuritySchema('Bearer', {
  type: 'http',
  scheme: 'bearer',
  bearerFormat: 'JWT',
  description: 'Bearer token for authenticating requests',
});

// 4. Documented routes
app.get(
  '/users/:id',
  openapi({
    summary: 'Get User by ID',
    description: 'Retrieves a user by their unique ID.',
    tags: ['User'],
    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(),
          })
        ),
      },
    },
  }),
  zValidatorYelix(
    'param',
    z.object({
      id: z.string().uuid(),
    })
  ),
  (c) => {
    const { id } = c.req.valid('param' as never) as { id: string };

    // Simulate user lookup
    const user = { id, name: 'John Doe', email: 'john@example.com' };

    return c.json(user);
  }
);

app.post(
  '/users',
  openapi({
    summary: 'Create User',
    description: 'Creates a new user',
    tags: ['User'],
    responses: {
      201: {
        description: 'User created successfully',
        content: zodToResponseSchema(
          z.object({
            id: z.uuid(),
            name: z.string(),
            email: z.email(),
          })
        ),
      },
      400: {
        description: 'Invalid input',
        content: zodToResponseSchema(
          z.object({
            error: z.string(),
            message: z.string(),
          })
        ),
      },
    },
  }),
  zValidatorYelix(
    'json',
    z.object({
      name: z.string().min(1),
      email: z.email(),
    })
  ),
  (c) => {
    const { name, email } = c.req.valid('json' as never) as { name: string; email: string };

    // Simulate user creation
    const user = {
      id: crypto.randomUUID(),
      name,
      email,
    };

    return c.json(user, 201);
  }
);

// 5. OpenAPI JSON endpoint
app.get('/openapi.json', openapi({ hide: true }), (c) => {
  return c.json(app.getOpenAPI());
});

Deno.serve(app.fetch);

Using Scalar UI

Combine OpenAPI with Scalar UI for beautiful documentation:

import { YelixHono } from '@yelix/hono';

const app = new YelixHono();

app.__openapi.setTitle('My API');
app.__openapi.setDescription('API Documentation');

// Add your routes here...

// Expose Scalar UI
app.exposeScalarOpenAPI({
  title: 'My API Documentation',
  openapiJsonPath: '/openapi.json',
  docsPath: '/docs',
});

Deno.serve(app.fetch);

Now visit /docs to see your interactive API documentation!

Next Steps

• Learn about Basic Setup
• Configure Servers and Security
• Learn about Documenting Endpoints