API Hello World

import { Card, CardContent, CardHeader, CardTitle } from ‘@astrojs/starlight/components’; import { Tabs } from ‘@astrojs/starlight/components’;

API Hello World

Un ejemplo completo de API Hello World que demuestra las características fundamentales del framework Veloce-TS.

Resumen

Este ejemplo muestra las capacidades principales de Veloce-TS a través de una API simple pero rica en características que incluye:

• Enrutamiento basado en decoradores con @Controller, @Get, @Post
• Validación de solicitudes usando esquemas Zod
• Extracción de parámetros de consulta con el decorador @Query
• Parámetros de ruta con @Param
• Validación del cuerpo de la solicitud con @Body
• Generación de documentación OpenAPI
• Soporte TypeScript con seguridad de tipos completa

Características Demostradas

🎯 Decoradores Principales

• @Controller('/hello') - Define la ruta base del controlador
• @Get('/') - Endpoint HTTP GET
• @Get('/:name') - Extracción de parámetros de ruta
• @Post('/') - Endpoint HTTP POST con validación del cuerpo

📝 Manejo de Parámetros

• @Param('name') - Extrae parámetros de ruta
• @Query() - Extrae parámetros de consulta (NUEVO en v0.2.6)
• @Body(Schema) - Valida el cuerpo de la solicitud con Zod

📚 Documentación

• @ApiDoc() - Añade documentación OpenAPI
• Generación automática de esquemas
• Documentación interactiva de la API

Estructura del Proyecto

hello_world/
├── src/
│   ├── controllers/
│   │   └── hello.controller.ts    # Controlador principal
│   └── index.ts                   # Punto de entrada de la aplicación
├── public/
│   └── docs.html                  # Documentación de la API
├── package.json
├── tsconfig.json
└── README.md

Endpoints de la API

1. Hello World Simple

GET /hello

Respuesta:

{
  "message": "Hello World!",
  "timestamp": "2025-10-15T19:12:09.119Z",
  "version": "1.0.0"
}

2. Saludo Personalizado

GET /hello/:name?language=es&format=text

Parámetros:

• name (ruta): El nombre a saludar
• language (consulta): Idioma para el saludo (en, es, fr)
• format (consulta): Formato de respuesta (json, text)

Ejemplos:

• GET /hello/Alfredo → "Hello, Alfredo!"
• GET /hello/Alfredo?language=es → "¡Hola, Alfredo!"
• GET /hello/Alfredo?language=fr&format=text → "Bonjour, Alfredo!"

3. Crear Saludo Personalizado

POST /hello
Content-Type: application/json

{
  "name": "Mundo",
  "message": "Saludo personalizado",
  "language": "es"
}

4. Listar Todos los Saludos

GET /hello/greetings

5. Obtener Saludo por ID

GET /hello/greetings/:id

6. Información de la API

GET /hello/api/info

Ejemplos de Código Clave

Configuración del Controlador

import {
  Controller,
  Get,
  Post,
  Body,
  Param,
  Query,
  ApiDoc
} from 'veloce-ts';
import { z } from 'zod';

const GreetingSchema = z.object({
  name: z.string().min(1, 'El nombre es requerido').max(50, 'Nombre muy largo'),
  message: z.string().optional(),
  language: z.enum(['en', 'es', 'fr']).optional().default('en'),
});

@Controller('/hello')
export class HelloController {
  private greetings: any[] = [];

  @Get('/')
  @ApiDoc({
    summary: 'Decir Hello World',
    description: 'Devuelve un mensaje hello simple'
  })
  async hello() {
    return {
      message: 'Hello World!',
      timestamp: new Date().toISOString(),
      version: '1.0.0'
    };
  }

  @Get('/:name')
  @ApiDoc({
    summary: 'Saludar a alguien',
    description: 'Devuelve un mensaje de saludo personalizado'
  })
  async helloName(
    @Param('name') name: string,
    @Query() query: any
  ) {
    const language = query?.language || 'en';
    const format = query?.format || 'json';

    const greeting = this.getGreeting(name, language);

    if (format === 'text') {
      return greeting;
    }

    return {
      message: greeting,
      name: name,
      language: language,
      timestamp: new Date().toISOString(),
      format: format
    };
  }

  @Post('/')
  @ApiDoc({
    summary: 'Crear un saludo personalizado',
    description: 'Almacena un mensaje de saludo personalizado'
  })
  async createGreeting(@Body(GreetingSchema) greeting: any) {
    const newGreeting = {
      ...greeting,
      id: this.greetings.length + 1,
      createdAt: new Date().toISOString()
    };

    this.greetings.push(newGreeting);

    return {
      message: 'Saludo creado exitosamente',
      id: newGreeting.id,
      greeting: newGreeting
    };
  }

  private getGreeting(name: string, language: string = 'en'): string {
    const greetings = {
      en: `Hello, ${name}!`,
      es: `¡Hola, ${name}!`,
      fr: `Bonjour, ${name}!`
    };

    return greetings[language as keyof typeof greetings] || greetings.en;
  }
}

import 'reflect-metadata';
import { VeloceTS } from 'veloce-ts';
import { HelloController } from './controllers/hello.controller';

const app = new VeloceTS({
  title: 'API Hello World Veloce-TS',
  version: '1.0.0',
  description: 'Una API Hello World simple que demuestra los fundamentos de Veloce-TS'
});

// Habilitar CORS para todos los orígenes
app.use('*', (c, next) => {
  c.header('Access-Control-Allow-Origin', '*');
  c.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  c.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  return next();
});

// Servir archivos estáticos
app.static('/public', './public');

// Incluir plugin OpenAPI para documentación
app.install('openapi');

// Incluir controladores
app.include(HelloController);

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log('🚀 API Hello World Veloce-TS está ejecutándose!');
  console.log('');
  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
  console.log(`🌐 Servidor:        http://localhost:${PORT}`);
  console.log(`📖 Docs API:        http://localhost:${PORT}/docs.html`);
  console.log(`📄 Spec OpenAPI:    http://localhost:${PORT}/openapi.json`);
  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
  console.log('');
  console.log('💡 Prueba estos endpoints:');
  console.log('  • GET  /hello');
  console.log('  • GET  /hello/:name');
  console.log('  • POST /hello');
  console.log('  • GET  /api/info');
  console.log('');
  console.log('🎉 ¡Feliz codificación!');
});

Qué hay de nuevo en v0.2.6

Este ejemplo demuestra el decorador @Query corregido que ahora funciona correctamente:

Antes (v0.2.5 y anteriores):

// Tenías que usar @Ctx() para extraer manualmente los parámetros de consulta
async helloName(@Param('name') name: string, @Ctx() c: any) {
  const query = c.req.query();
  const language = query?.language || 'en';
}

Ahora (v0.2.6):

// Limpio y simple con el decorador @Query()
async helloName(@Param('name') name: string, @Query() query: any) {
  const language = query?.language || 'en';
}

Inicio Rápido

1. Crear un nuevo proyecto:

   bun veloce-ts new hello_world --template rest
   cd hello_world

2. Instalar dependencias:

   bun install

3. Reemplazar el controlador generado con el código de HelloController de arriba

4. Actualizar package.json para usar la última versión:

   {
     "dependencies": {
       "veloce-ts": "^0.2.6"
     }
   }

5. Ejecutar el servidor:

   bun run dev

6. Probar la API:

   # Hello simple
   curl http://localhost:3000/hello
   
   # Saludo personalizado en español
   curl "http://localhost:3000/hello/Alfredo?language=es"
   
   # Saludo en formato texto en francés
   curl "http://localhost:3000/hello/World?language=fr&format=text"

Ruta de Aprendizaje

Este ejemplo es perfecto para:

• Principiantes aprendiendo fundamentos de Veloce-TS
• Entender decoradores y su uso
• Aprender extracción de parámetros con @Query, @Param, @Body
• Explorar validación con esquemas Zod
• Entender generación de documentación OpenAPI

Próximos Pasos

Después de dominar este ejemplo, explora:

• Ejemplo TaskMaster - Aplicación completa con autenticación, RBAC y base de datos
• Guía de Decoradores - Referencia completa de decoradores
• Inyección de Dependencias - Patrones avanzados de DI
• Guía de Plugins - Extender funcionalidad de Veloce-TS

Documentación de la API

Una vez ejecutándose, visita:

• Documentación Interactiva: http://localhost:3000/docs.html
• Especificación OpenAPI: http://localhost:3000/openapi.json

¡Este ejemplo proporciona una base sólida para construir aplicaciones Veloce-TS más complejas!