> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI

> Cada función genera automáticamente una especificación OpenAPI 3.1 accesible en /openapi.json.

## Endpoint automático

Toda función desplegada expone su especificación OpenAPI en:

```
https://<slug>.fn.jelou.ai/openapi.json
```

Este endpoint es **siempre público** — no requiere `X-Jelou-Token`, sin importar la configuración de autenticación.

## Ejemplo

Para una función con esta definición:

```typescript index.ts theme={null}
import { define, z } from "@jelou/functions";

export default define({
  name: "consultar-saldo",
  description: "Consulta el saldo de un cliente por teléfono",
  input: z.object({
    telefono: z.string().min(10).describe("Número con código de país"),
  }),
  output: z.object({
    nombre: z.string(),
    saldo: z.number(),
  }),
  handler: async (input) => ({
    nombre: "María García",
    saldo: 150.00,
  }),
});
```

La spec generada en `/openapi.json`:

```json theme={null}
{
  "openapi": "3.1.0",
  "info": {
    "title": "consultar-saldo",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "consultar-saldo",
        "summary": "Consulta el saldo de un cliente por teléfono",
        "security": [{ "jelouToken": [] }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "telefono": {
                    "type": "string",
                    "minLength": 10,
                    "description": "Número con código de país"
                  }
                },
                "required": ["telefono"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "nombre": { "type": "string" },
                    "saldo": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "jelouToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Jelou-Token"
      }
    }
  }
}
```

## Funciones públicas vs protegidas

| Config                     | `security` en la spec    |
| -------------------------- | ------------------------ |
| Sin `public` (default)     | `[{ "jelouToken": [] }]` |
| `config: { public: true }` | `[]` (sin seguridad)     |

En modo `app()`, cada tool puede tener su propia configuración de `public`, y la spec refleja esto por ruta.

## Multi-tool

En modo `app()`, la spec incluye una ruta por cada tool:

```json theme={null}
{
  "paths": {
    "/crear-contacto": { "post": { "operationId": "crearContacto", ... } },
    "/buscar-contactos": { "get": { "operationId": "buscarContactos", ... } },
    "/eliminar-contacto": { "post": { "operationId": "eliminarContacto", ... } }
  }
}
```

## Probar en local

```bash theme={null}
jelou functions dev
curl http://localhost:3000/openapi.json | jq .
```

## Uso con Swagger UI

Puedes visualizar la spec con cualquier herramienta compatible con OpenAPI:

```bash theme={null}
# Descargar la spec
curl https://mi-funcion.fn.jelou.ai/openapi.json -o openapi.json

# Abrirla en Swagger Editor online
# Pega el contenido en https://editor.swagger.io
```

<Tip>
  Las anotaciones `.describe()` de Zod se convierten en el campo `description` de cada propiedad en la spec. Esto mejora la documentación automática de tu API.
</Tip>