El contrato OpenAPI como requisito

Un contrato OpenAPI es un documento en YAML o JSON que describe una API: sus rutas, los métodos de cada ruta, los parámetros, los esquemas de lo que se envía y de lo que se recibe, y los esquemas de seguridad que exige cada operación. La especificación la mantiene la OpenAPI Initiative, un proyecto abierto de la Linux Foundation, y hoy conviven contratos de la línea 3.x con contratos viejos en el formato 2.0, que todavía se llamaba Swagger.

Para quien revisa seguridad, el valor del contrato no está en la documentación bonita que genera, sino en que convierte la intención en algo verificable. Si el contrato dice que una operación exige sesión, que un texto no pasa de 120 caracteres o que un campo solo sale y nunca entra, eso se puede revisar en papel, se puede exigir en la pasarela y se puede probar automáticamente. Lo que el contrato no dice, nadie lo puede comprobar.

Ojo con la trampa de esta sala: un validador de formato comprueba que el documento está bien escrito, no que lo escrito sea seguro. Un contrato perfectamente válido puede declarar una operación sin autenticación que devuelve datos de clientes.

Abre el laboratorio y lee pedidos-v2.yaml con politica-apis.txt al lado. En OpenAPI, el bloque security de la raíz se aplica a todas las operaciones, y una operación puede reemplazarlo con el suyo. Una lista vacía en una operación significa que esa operación no exige nada. A veces es legítimo; la política de Tasajera dice cuándo.

Busca las operaciones que anulan la seguridad global, mira qué esquema devuelve cada una y crúzalo con la regla R2 y con las notas del equipo.

Un texto sin longitud máxima no es un fallo por sí solo, pero deja sin acotar lo que el servicio tendrá que guardar, procesar y devolver, y le quita a la pasarela una regla que podría aplicar sin saber nada del negocio. Por eso la regla R3 exige maxLength en toda propiedad de tipo string que no esté ya acotada por una lista de valores (enum) o por un formato (format).

Recorre los cinco esquemas de components.schemas y cuenta las propiedades de tipo texto que incumplen R3. Los parámetros de ruta no cuentan: solo las propiedades de los esquemas.

Un esquema de entrada es una lista de lo que el cliente puede proponer. Si en esa lista aparece algo que solo el servidor debería decidir, el contrato está invitando al cliente a decidirlo, y el código tendrá que acordarse de ignorarlo cada vez. Es la misma familia de fallos de la asignación masiva, vista desde el contrato. OpenAPI ofrece readOnly para marcar las propiedades que solo salen, pero lo más limpio es no tenerlas en el esquema de entrada.

Compara el esquema de entrada del pedido con el de salida y con la regla R4. Las notas del equipo cuentan por qué alguien lo agregó.

El equipo quiere publicar el contrato como aprobado. Tienes tres hallazgos de diseño en un documento que el validador de formato dio por bueno. La respuesta útil no es «no» ni una lista de reglas, sino qué cambiar en el contrato para que lo que se construya a partir de él ya nazca correcto.