Ejemplos de la API de multas que compilan: por qué importan

Una integración de flota rara vez empieza por el esquema. Empieza por la documentación: alguien copia el primer bloque de código y lo pega en una terminal. Ese fragmento, y no el archivo OpenAPI, es el contrato que se ejecuta primero: fija los nombres de campo que van a quedar escritos en el cliente, el orden de las llamadas y la forma esperada de una respuesta.

El problema es que un ejemplo se escribe a mano una vez y la API sigue cambiando. Cuando el campo del importe se renombra o un estado del acta deja de emitirse, nada falla: el sitio de documentación se publica igual, la suite de tests pasa igual, y el error aparece más tarde en la máquina de quien integra, que razonablemente concluye que la API está rota.

Un ejemplo que compila es el que dejó de ser prosa. Se extrae de la documentación, se parsea, se valida contra el esquema que dice ilustrar y, cuando corresponde, se ejecuta contra el sandbox de infracciones en cada build. Si algo de eso falla, rompe la construcción como cualquier otra prueba.

Qué quiere decir que un ejemplo compile

Lo sintáctico va primero. Un ejemplo de respuesta tiene que ser JSON válido: la gramática de RFC 8259 delimita las cadenas con comillas dobles, coloca el separador sólo entre elementos y no contempla comentarios. Una abreviación habitual —recortar un payload largo con puntos suspensivos fuera de una cadena— produce algo que no parsea en ningún cliente.

Sigue lo estructural: el ejemplo cumple el esquema que lo acompaña. Campos requeridos presentes, tipos correctos, valores dentro del enum declarado, como el estado de un acta.

Y queda el comportamiento: el fragmento ejecutable corre contra el sandbox y devuelve lo que la página promete. Cada nivel detecta una deriva distinta, y sólo el último advierte que el endpoint de consulta por patente cambió de ruta o de códigos de estado.

examples describe, no comprueba

En JSON Schema 2020-12, examples vive entre las palabras clave de metadatos: ilustra el uso y no altera el resultado de la validación. OpenAPI define campos de ejemplo en varios lugares del documento —el objeto de esquema, el media type, los parámetros— y recomienda que el ejemplo coincida con el esquema declarado. Ambas lo plantean como recomendación para quien escribe, no como una regla que la herramienta haga cumplir.

Un documento con un ejemplo inconsistente sigue siendo un documento cargable. Por eso la coherencia se verifica afuera: se toma cada ejemplo, se lo valida contra el mismo esquema y dialecto que usan las herramientas del proyecto, y se reporta el desvío con la ruta exacta del campo.

Lo que enseña un ejemplo viejo

Lo que un ejemplo muestra se propaga a cada flota que lo copió, y eso lo vuelve un canal de enseñanza silencioso:

• un campo renombrado que sobrevive en el ejemplo produce integraciones construidas sobre un nombre que ya no existe;
• un estado retirado que sigue apareciendo enseña a esperar una transición que no va a llegar;
• un ejemplo que sólo muestra el caso feliz enseña que no existen respuestas parciales ni fuentes caídas;
• un campo deprecado encuentra en los ejemplos su último refugio.

De ahí que actualizar los ejemplos pertenezca al cambio que modifica el contrato y no a una tarea posterior. Cuando se avisa que un campo va a desaparecer, el ejemplo es la primera evidencia de que el aviso es en serio: sobre eso trata deprecar un campo.

Datos de ejemplo que no deberían salir a la calle

Un ejemplo ejecutable no es sólo texto: es una solicitud que alguien va a disparar. El mismo control que lo parsea puede revisar a dónde apunta y con qué patente. RFC 5737 reserva tres bloques IPv4 para usar en ejemplos de especificaciones y otros documentos, y hay dominios pensados con el mismo fin: un host tomado de ahí no se convierte en tráfico hacia un tercero.

Los identificadores siguen la regla del sandbox, y preferimos que esa revisión sea automática: un dato real —la patente de un cliente, el número de un acta— colado en un ejemplo recién se descubre cuando ya está copiado. Una credencial de ejemplo también se commitea a veces, así que conviene que sea inválida por construcción y no una clave real acortada.

Cómo automatizarlo sin duplicar trabajo

Hay dos caminos y convergen. El primero trata la documentación como fuente: cada bloque declara su lenguaje y el esquema o endpoint que ilustra, y el pipeline los extrae, parsea, valida y ejecuta contra el sandbox los marcados como ejecutables, con una credencial dedicada.

El segundo genera el ejemplo desde el mismo fixture que usan los tests de contrato, de modo que la página no pueda desviarse de la respuesta real. Así el ejemplo envejece cuando envejece el sandbox, no antes.

Antes de publicar, revisá: que cada ejemplo de respuesta valide contra el esquema del estado que dice representar; que exista al menos un caso no feliz —una jurisdicción caída, un resultado parcial—; que ningún identificador sea real; y que la página indique contra qué versión de la API corrieron los ejemplos.

Un ejemplo que no corre no es documentación. Es una hipótesis con formato de código, y quien la copia no tiene manera de saberlo.

Metodología

Alcance

Tratamiento de los ejemplos de una documentación de API como artefactos verificables. No cubre la elección de herramientas de documentación ni la validación del servicio contra su especificación.

Unidad de análisis

Un bloque de ejemplo publicado, con el esquema o endpoint que dice ilustrar y el resultado de parsearlo, validarlo y ejecutarlo.

Cobertura

Semántica de OpenAPI 3.1 y JSON Schema 2020-12 sobre campos de ejemplo, gramática JSON de RFC 8259 y bloques reservados para documentación de RFC 5737.

Limitaciones

• Los ejemplos en lenguajes de cliente requieren compilar o ejecutar en cada entorno, y eso depende de la infraestructura de integración continua disponible.
• Validar un ejemplo contra su esquema no dice nada sobre si el esquema describe correctamente el comportamiento del servicio.
• Un ejemplo ejecutable consume cuota del sandbox y necesita credenciales propias, aisladas de las de producción.

Fuentes

• OpenAPI Specification version 3.1.2 — OpenAPI Initiative (consultada el 2026-08-29)
• JSON Schema Validation Draft 2020-12 — JSON Schema (consultada el 2026-08-29)
• RFC 8259 — The JavaScript Object Notation Data Interchange Format — RFC Editor (consultada el 2026-08-29)
• IPv4 Address Blocks Reserved for Documentation — RFC Editor (consultada el 2026-08-29)

Preguntas frecuentes

¿Un ejemplo válido en la documentación garantiza que la API responde así?

No. Sólo garantiza que el ejemplo parsea y cumple el esquema que se le asignó. Que la respuesta real coincida con esa forma es otra verificación: hace falta ejecutarlo contra un entorno de prueba y comparar, o generarlo desde la misma respuesta del sandbox.

¿El campo `examples` de JSON Schema valida el ejemplo contra el esquema?

No. En JSON Schema 2020-12 vive entre las palabras clave de metadatos: sirve para ilustrar el uso y no cambia el resultado de la validación. El texto recomienda que esos valores sean válidos contra el esquema asociado, pero lo dice como recomendación, no como algo que el validador haga cumplir. Si querés la garantía, tomá el ejemplo y validalo aparte, con el mismo dialecto que usa el resto del proyecto.

¿Por qué no usar una patente o una credencial reales en los ejemplos?

Porque un ejemplo se copia, se pega y a veces se commitea. Conviene que los identificadores sean evidentemente ficticios, que el entorno productivo los rechace y que las direcciones o dominios usados sean los reservados para documentación, para que un copiar y pegar no contacte a un tercero.

Notas relacionadas