# 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.