OpenAPI - Jelou AI Docs

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:

index.ts

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:

{
  "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:

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

Probar en local

jelou functions dev
curl http://localhost:3000/openapi.json | jq .

Uso con Swagger UI

Puedes visualizar la spec con cualquier herramienta compatible con OpenAPI:

# 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

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.

​Endpoint automático

​Ejemplo

​Funciones públicas vs protegidas

​Multi-tool

​Probar en local

​Uso con Swagger UI

Endpoint automático

Ejemplo

Funciones públicas vs protegidas

Multi-tool

Probar en local

Uso con Swagger UI