Guía de integración del componente ApiTester en Starlight

Esta guía te muestra cómo integrar el componente ApiTester en tu documentación de Starlight para crear una experiencia interactiva de prueba de APIs.

Paso 1: Crear la estructura de carpetas

Primero, asegúrate de tener una estructura de carpetas adecuada en tu proyecto Starlight:

.
├── src/
│   ├── components/
│   │   ├── ApiTester.jsx    # El componente principal
│   │   └── ApiTester.css    # Estilos del componente
│   │
│   └── content/
│       └── docs/
│           ├── api/
│           │   ├── users.mdx    # Documentación de la API de usuarios
│           │   ├── products.mdx # Documentación de la API de productos
│           │   └── ...
│           └── ...
└── ...

Paso 2: Configurar Astro para usar componentes React

Asegúrate de que tu proyecto Astro está configurado para usar componentes React. Si no lo has hecho aún:

1. Instala las dependencias necesarias:

npm install react react-dom

2. Actualiza tu archivo astro.config.mjs para incluir la integración de React:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import react from '@astrojs/react';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Mi Documentación de API',
      // otras configuraciones de Starlight...
    }),
    react() // Añadir la integración de React
  ],
});

Paso 3: Copiar los archivos del componente

1. Copia el archivo ApiTester.jsx en la carpeta src/components/.
2. Copia el archivo ApiTester.css en la misma carpeta.

Paso 4: Usar el componente en tus archivos MDX

Ahora puedes usar el componente ApiTester en cualquier archivo MDX de tu documentación:

---
title: API de Productos
description: Documentación de la API de productos
---

import ApiTester from '../../components/ApiTester.jsx';

# API de Productos

## Listar productos

<ApiTester
  method="GET"
  endpoint="/api/products"
  description="Recupera una lista paginada de productos."
  parameters={[
    {
      name: "page",
      type: "integer",
      default: "1",
      required: false,
      description: "Número de página"
    },
    // Más parámetros...
  ]}
  // Más configuraciones...
/>

Paso 5: Personalización adicional (opcional)

Temas claro/oscuro

El componente ya está preparado para funcionar con los temas claro y oscuro de Starlight. Si necesitas ajustar los colores:

1. Abre ApiTester.css
2. Modifica las variables CSS utilizadas o agrega nuevas en las secciones específicas para temas.

Adaptar el dominio base

Si necesitas configurar un dominio base diferente para tus APIs:

<ApiTester
  method="GET"
  endpoint="/api/products"
  baseUrl="https://api.midominio.com" // Añade esta propiedad
  // Resto de la configuración...
/>

Para esto, deberás actualizar el componente ApiTester.jsx para que acepte esta nueva propiedad.

Paso 6: Documentar múltiples versiones de API (opcional)

Si necesitas documentar múltiples versiones de tu API, puedes estructurar tus carpetas de la siguiente manera:

src/content/docs/
├── api/
│   ├── v1/
│   │   ├── users.mdx
│   │   └── products.mdx
│   └── v2/
│       ├── users.mdx
│       └── products.mdx
└── ...

Y luego usar el componente con la versión apropiada:

<ApiTester
  method="GET"
  endpoint="/v2/api/products"
  // Resto de la configuración...
/>

Solución de problemas comunes

Los estilos no se aplican correctamente

Asegúrate de que el archivo CSS está siendo importado correctamente. Puedes modificar el componente para importar los estilos directamente:

// En ApiTester.jsx
import { useState } from 'react';
import './ApiTester.css'; // Asegúrate de que esta línea esté presente

El componente no funciona en producción

Si el componente funciona en desarrollo pero no en producción:

1. Verifica que estás usando la integración de React correctamente.
2. Asegúrate de que la configuración de CORS de tu API permite solicitudes desde el dominio donde está alojada tu documentación.

Los ejemplos de respuesta no se muestran adecuadamente

Asegúrate de escapar correctamente las comillas en los ejemplos JSON cuando los defines en MDX:

responses={[
  {
    status: 200,
    description: "Éxito",
    example: `{
  "data": {
    "id": 123,
    "name": "Producto"
  }
}`  // Usa backticks (`) para cadenas multilínea
  }
]}