Generar Documentación

Aprende a crear documentación profesional para tus APIs con páginas personalizadas, ejemplos y más.

Contenido

Introducción

GetMan permite generar documentación profesional y atractiva para tus APIs de forma automática. La documentación se genera a partir de tus colecciones, incluyendo todos los endpoints, parámetros, headers, body y ejemplos que hayas definido.

Además, puedes crear páginas personalizadas como introducciones, guías de uso, notas de versión, y cualquier contenido adicional que desees incluir en tu documentación.

💡 Consejo: Una buena documentación incluye no solo la referencia de endpoints, sino también guías de inicio rápido, ejemplos de uso común y notas importantes.

Configuración de Documentación

Para acceder a la configuración de documentación de una colección:

  1. 1

    Abre tu colección en el workspace

  2. 2

    Haz clic en el menú de la colección (tres puntos)

  3. 3

    Selecciona "Configurar Documentación"

Opciones de Configuración

Título de la Documentación

Personaliza el título que aparecerá en la documentación. Por defecto usa el nombre de la colección.

Descripción

Una descripción general de tu API que aparecerá en la parte superior de la documentación.

URL Base

Define la URL base de tu API (ej: https://api.ejemplo.com/v1). Se mostrará en todos los endpoints.

Logo

Sube el logo de tu empresa o proyecto para personalizar la documentación.

Color Primario

Personaliza el color de acento de la documentación para que coincida con tu marca.

Habilitar "Try It"

Permite a los usuarios probar los endpoints directamente desde la documentación.

Crear Páginas Personalizadas

Las páginas personalizadas te permiten añadir contenido adicional a tu documentación como:

  • Introducción y descripción general
  • Guías de inicio rápido
  • Ejemplos de uso común
  • Notas de versión (changelog)
  • Preguntas frecuentes (FAQ)
  • Información de autenticación
  • Límites y cuotas de la API

Cómo crear una página

  1. 1

    Ve a la configuración de documentación de tu colección

  2. 2

    Busca la sección "Páginas de Documentación"

  3. 3

    Haz clic en "Agregar Página"

  4. 4

    Completa el formulario:

    • Icono: Un emoji para identificar la página (opcional)
    • Título: El nombre de la página
    • Contenido: El contenido en formato Markdown
    • Publicado: Si está visible en la documentación

Formato Markdown

El contenido de las páginas se escribe en formato Markdown, lo que te permite crear contenido rico y bien formateado: 

# Título Principal

## Subtítulo

Texto normal con **negrita** y *cursiva*.

### Listas

- Item 1
- Item 2
- Item 3

### Código

```json
{
  "nombre": "ejemplo",
  "valor": 123
}
```

### Enlaces

[Texto del enlace](https://ejemplo.com)

### Tablas

| Columna 1 | Columna 2 |
|-----------|-----------|
| Valor 1   | Valor 2   |

### Citas

> Esta es una cita importante

💡 Tip: Puedes reorganizar el orden de las páginas arrastrándolas en la lista de páginas.

Documentar Endpoints

Cada petición en tu colección se convierte automáticamente en un endpoint documentado. Para mejorar la documentación de cada endpoint, asegúrate de completar:

📝 Nombre Descriptivo

Usa nombres claros como "Obtener lista de usuarios" en lugar de "GET users".

📋 Descripción

Explica qué hace el endpoint, cuándo usarlo y cualquier nota importante.

🔤 Parámetros

Documenta cada parámetro con su descripción para que los usuarios entiendan su propósito.

📦 Body de Ejemplo

Incluye ejemplos realistas del body para peticiones POST, PUT y PATCH.

Agregar Ejemplos

Los ejemplos muestran casos de uso reales de cada endpoint. Cada ejemplo puede incluir:

  • Nombre descriptivo del ejemplo
  • Body de la petición (si aplica)
  • Código de estado de la respuesta
  • Body de la respuesta

Ejemplo: Endpoint de Login

Ejemplo 1: Login exitoso

200 OK Respuesta con token JWT

Ejemplo 2: Credenciales inválidas

401 Unauthorized Error de autenticación

Ejemplo 3: Datos incompletos

422 Validation Error de validación

Publicar Documentación

GetMan ofrece dos modos de publicación:

Pública

Cualquier persona con el enlace puede ver la documentación. Ideal para APIs públicas.

/docs/tu-coleccion-abc123

Privada con Token

Requiere un token de acceso para ver la documentación. Ideal para APIs internas.

/docs/tu-coleccion-abc123?token=secreto

⚠️ Importante: El token de acceso se genera automáticamente y puedes regenerarlo en cualquier momento desde la configuración.

Exportar a HTML

Puedes exportar tu documentación como un archivo HTML estático para:

  • Alojar en tu propio servidor
  • Incluir en repositorios de código
  • Distribuir como archivo offline
  • Integrar en sitios web existentes

Pasos para exportar

  1. 1. Ve a la configuración de documentación
  2. 2. Haz clic en el botón "Exportar HTML"
  3. 3. Se descargará un archivo HTML completo con estilos incluidos
  4. 4. Sube el archivo a cualquier servidor web

¿Listo para documentar tu API?

Comienza a crear documentación profesional para tus colecciones ahora mismo.

Importar Colección Crear Cuenta Gratis