# Especificación OpenAPI Dónde encontrar la descripción OpenAPI legible por máquina de la API, para qué sirve y cómo generar un cliente a partir de ella. La API de PDF Blocks se describe con un único documento OpenAPI: el contrato legible por máquina contra el que está escrita esta documentación. Es **OpenAPI 3.0.0**, actualmente en la versión `1.18.0`, publicado como `pdfblocks.openapi.yaml`. Allí están definidas todas las rutas, parámetros, enumeraciones, restricciones y respuestas de la API, así que puede generar un cliente tipado, validar las solicitudes antes de que salgan de su proceso o levantar un servidor simulado. <Note> [No hay un SDK oficial](/docs/api/libraries-and-integrations): HTTP directo es la vía de primera clase, y generar código a partir de esta especificación es la forma admitida de obtener un cliente tipado. Pronto habrá una URL de descarga alojada; por ahora, solicite el `pdfblocks.openapi.yaml` actual a [support@pdfblocks.com](mailto:support@pdfblocks.com). </Note> ## Para qué sirve la especificación - **Clientes tipados.** Genere modelos y métodos de solicitud en su lenguaje en lugar de escribir a mano las llamadas multipart. - **Validación.** Compruebe solicitudes y respuestas contra el esquema en sus pruebas o en el borde de su servicio. - **Simulación.** Cargue el documento en un servidor simulado para desarrollar contra él antes de conectar llamadas reales. - **Ayuda del editor.** Ábralo en un editor compatible con OpenAPI para tener autocompletado y documentación en línea. ## Generar un cliente tipado Guarde el contrato localmente como `pdfblocks.openapi.yaml` y luego apunte un generador de código a él. [OpenAPI Generator](https://openapi-generator.tech) es el que cubre más lenguajes; así se genera el andamiaje de un cliente de Python: ```bash title="openapi-generator" npm install -g @openapitools/openapi-generator-cli openapi-generator-cli generate \ -i pdfblocks.openapi.yaml \ -g python \ -o ./pdfblocks-client ``` Cambie `-g python` por `ruby`, `csharp`, `typescript-fetch`, `go`, `php` o cualquier otro generador admitido. Dos alternativas habituales: <CodeGroup> ```bash title="Swagger Codegen" # Multi-language generator, similar to OpenAPI Generator. swagger-codegen generate \ -i pdfblocks.openapi.yaml \ -l java \ -o ./pdfblocks-client ``` ```bash title="openapi-typescript" # TypeScript types only (no runtime client): pairs well with fetch. npx openapi-typescript pdfblocks.openapi.yaml \ --output ./pdfblocks.d.ts ``` </CodeGroup> Cualquiera sea la herramienta que use, configure el cliente generado con la URL base `https://api.pdfblocks.com` y envíe su clave en la cabecera `X-API-Key`. Consulte [Bibliotecas e integraciones](/docs/api/libraries-and-integrations) para ver el panorama completo de las superficies de integración admitidas. ## Especificación frente a documentación La especificación es la verdad para la máquina; esta documentación es la verdad para las personas. El documento OpenAPI le da la forma exacta de cada solicitud y de cada respuesta. La documentación en prosa añade lo que un esquema no puede: *por qué* y *cuándo* usar una acción, ejemplos resueltos en siete lenguajes, el catálogo de plantillas de marcas de agua y la recuperación ante errores. Use las dos: la especificación para generar y validar, la documentación para entender. El código del cliente se genera contra una versión concreta. Antes de fijar un cliente generado, lea [Versionado y estabilidad](/docs/api/versioning-and-stability) para saber qué cambios son retrocompatibles y cómo se publican los cambios incompatibles.