Archivo OpenAPI y clientes generados

• JSON: https://docs.filmo.io/openapi.json
• YAML: https://docs.filmo.io/openapi.yaml

Ambos ficheros describen el mismo contrato. La versión y la fecha de la instantánea con la que se construye esta documentación figuran en la Referencia de OpenAPI junto con un índice de todos los esquemas. La política de compatibilidad se describe en Versionado. Sea cual sea el servidor que elija tu herramienta, envía las peticiones a https://app.filmo.io.

• Es OpenAPI 3.1. Un valor anulable se escribe como type: ["string", "null"], y las uniones usan anyOf. Las herramientas que solo entienden 3.0 interpretan mal ambos.
• Cada operación tiene un operationId estable, el nombre que usan los documentos (GET /api/v1/orders, POST /api/v1/orders).
• Los nombres de esquema terminan en Dto para lo que devuelve la API y en Body para lo que envías (OrderUpdateBody). Los clientes generados los exponen como nombres de tipo.
• El dinero es una cadena decimal como "1234.50", nunca un número flotante. Guárdalo como cadena o como tipo decimal en tu cliente.
• Cada operación indica su permiso (scope) en x-required-scope y sus cuotas en x-rateLimit.

npx openapi-typescript https://docs.filmo.io/openapi.json -o filmo.d.ts

Combina los tipos con un pequeño envoltorio de fetch como openapi-fetch. Las claves de ruta incluyen el prefijo /api/v1.

import createClient from "openapi-fetch";
import type { paths } from "./filmo";

const client = createClient<paths>({
  baseUrl: process.env.FILMO_BASE_URL ?? "https://app.filmo.io",
  headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` },
});

const { data, error } = await client.GET("/api/v1/account");
if (error) throw new Error(error.code);
console.log(data.data.name);

OpenAPI Generator cubre typescript-fetch, python, csharp, java, php y go, entre otros. Fija la ruta base en https://app.filmo.io en la configuración generada y envía la clave como token bearer.

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.filmo.io/openapi.json \
  -g typescript-fetch \
  -o ./filmo-client

openapi-python-client generate --url https://docs.filmo.io/openapi.json

Las respuestas de disponibilidad son uniones: cada entrada es uno de varios esquemas con nombre (un resultado, o una entrada que indica que no se encontró el artículo o el recurso). Los generadores difieren en cómo manejan anyOf, así que genera el cliente y prueba las operaciones de disponibilidad antes de fiarte de ellas. El estado de cada generador, con la versión probada y los problemas conocidos, está en la tabla de Generadores que probamos.

Filmo ejecuta generadores contra el archivo. Para cada herramienta, la tabla indica la versión probada, las opciones usadas, el resultado y los problemas conocidos.

1. 1

   Importar por enlace

   En el diálogo de importación de tu herramienta, elige la opción de importar desde un enlace o URL y pega https://docs.filmo.io/openapi.json. Importar el archivo descargado también funciona.

2. 2

   Definir la URL base

   Comprueba el servidor que ha elegido el importador y ponlo en https://app.filmo.io.

3. 3

   Añade la clave

   Elige la autenticación con bearer token y guarda la clave como variable secreta o valor de entorno, nunca en la propia colección.

4. 4

   Haz tu primera llamada

   Ejecuta GET /api/v1/account para confirmar la clave y ver sus permisos (scopes).

Si un importador muestra tipos extraños, la causa suele ser la notación type: [..., "null"] o anyOf. La petición sigue funcionando.

• Enums cerrados: un nuevo estado o tipo puede llegar dentro de v1 como cambio aditivo. Si tu generador puede asignar los valores de enum desconocidos a un valor de reserva, actívalo; si no, envuelve el análisis de la respuesta para que un solo valor desconocido no haga fallar toda la llamada.
• Validación estricta de la respuesta: no rechaces las propiedades desconocidas.
• Regenera a propósito. Lee antes el changelog, luego regenera y revisa el diff del código generado.

Prism sirve una API falsa a partir del archivo OpenAPI. Úsalo para ejercitar tu análisis, tu gestión de errores y tus rutas de escritura sin tocar datos reales.

npm install --global @stoplight/prism-cli
prism mock -d https://docs.filmo.io/openapi.json

# In another terminal. Prism listens on port 4010 by default.
curl -s http://127.0.0.1:4010/api/v1/account -H "Authorization: Bearer $FILMO_API_KEY"

Un mock devuelve datos generados. Los campos decimales vuelven como cadenas de relleno, como "string", no como importes del estilo "1234.50", y el mock no guarda nada, así que no puede mostrar repeticiones idempotentes, cambios de ETag ni los límites de peticiones reales. Para eso, sigue la guía de pruebas.

Más sobre formas seguras de probar: Pruebas.