Que Es OpenAPI?

La especificacion OpenAPI (anteriormente conocida como Swagger) es un formato estandar para describir APIs REST. Define cada aspecto de una API en un documento legible por maquinas: endpoints, metodos HTTP, parametros de request, formatos de response, autenticacion y modelos de datos.

Un spec de OpenAPI sirve como contrato entre proveedores y consumidores de la API. Como tester, es tu fuente de verdad sobre lo que la API deberia hacer.

OpenAPI vs. Swagger

  • Swagger fue el nombre original, creado por SmartBear
  • OpenAPI se convirtio en el nombre estandar despues de que la especificacion fue donada a la Linux Foundation
  • Swagger UI y Swagger Editor son herramientas que trabajan con specs OpenAPI
  • Version actual: OpenAPI 3.1 (alineada con JSON Schema)

Leyendo una Especificacion OpenAPI

Los specs OpenAPI se escriben en YAML o JSON. Aqui un ejemplo simplificado:

openapi: 3.1.0
info:
  title: API de Gestion de Usuarios
  version: 1.0.0
  description: API para gestionar usuarios

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: Listar todos los usuarios
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Respuesta exitosa
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Crear un nuevo usuario
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: Usuario creado
        '400':
          description: Error de validacion

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: integer
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
        createdAt:
          type: string
          format: date-time

    CreateUser:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
          default: user

Secciones Clave

SeccionProposito
infoTitulo, version, descripcion de la API
serversURLs base para diferentes ambientes
pathsEndpoints con metodos y parametros
components/schemasModelos de datos reutilizables
securityRequisitos de autenticacion

Fundamentos de JSON Schema

JSON Schema define la estructura y reglas de validacion para datos JSON. OpenAPI usa JSON Schema para bodies de request y response.

Tipos y Restricciones Comunes 

# String con restricciones
name:
  type: string
  minLength: 1
  maxLength: 255
  pattern: "^[A-Za-z ]+$"

# Numero con rango
age:
  type: integer
  minimum: 0
  maximum: 150

# Enum (valores permitidos)
status:
  type: string
  enum: [active, inactive, suspended]

# Array con tipo de item
tags:
  type: array
  items:
    type: string
  minItems: 1
  maxItems: 10
  uniqueItems: true

# Campo nullable
deletedAt:
  type: ["string", "null"]
  format: date-time

Casos de Test desde el Schema

Cada restriccion del schema genera casos de test:

Regla del SchemaTest PositivoTest Negativo
required: [name]Incluir campo nameOmitir campo name
minLength: 1Enviar "A"Enviar "" (vacio)
maxLength: 100Enviar 100 caracteresEnviar 101 caracteres
minimum: 0Enviar 0Enviar -1
enum: [a, b, c]Enviar "a"Enviar "d"
type: integerEnviar 42Enviar "cuarenta y dos"
format: emailEnviar a@b.comEnviar no-es-email

Validacion de Schema en Practica

Validando con Postman

Usa la validacion de JSON Schema integrada de Postman:

// En tab Tests
const schema = {
  type: "object",
  required: ["id", "name", "email"],
  properties: {
    id: { type: "number" },
    name: { type: "string" },
    email: { type: "string", format: "email" },
    role: { type: "string", enum: ["admin", "user", "viewer"] }
  },
  additionalProperties: false
};

pm.test("Response coincide con schema", function () {
  const response = pm.response.json();
  const valid = tv4.validate(response, schema);
  pm.expect(valid).to.be.true;
});

Validando con Python (jsonschema) 

import jsonschema
import requests

schema = {
    "type": "object",
    "required": ["id", "name", "email"],
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"}
    }
}

response = requests.get("https://api.example.com/users/1")
data = response.json()

try:
    jsonschema.validate(instance=data, schema=schema)
    print("Validacion de schema exitosa")
except jsonschema.ValidationError as e:
    print(f"Validacion de schema fallida: {e.message}")

Testing Automatizado de Schema con Schemathesis

Schemathesis genera casos de test automaticamente desde tu spec OpenAPI:

pip install schemathesis

# Ejecutar contra una API activa
schemathesis run https://api.example.com/openapi.json

# Con verificaciones especificas
schemathesis run https://api.example.com/openapi.json \
  --checks all \
  --stateful=links

Automaticamente testea valores limite, tipos invalidos, campos faltantes y mas — todo derivado del spec.

Estrategia de Testing Basada en Specs

Testing de Spec vs. Implementacion

  1. La implementacion coincide con el spec? — Validar que las respuestas reales cumplan con los schemas documentados
  2. El spec esta completo? — Buscar endpoints, campos o codigos de error no documentados
  3. Las restricciones se aplican? — Verificar que las validaciones de minLength, maxLength, enum, format realmente funcionen
  4. Los casos borde se manejan? — Testear campos nullable, campos opcionales, propiedades adicionales

Bugs Comunes de Schema

BugComo Encontrarlo
Campos requeridos faltantes en responseValidar contra schema
Tipos de datos incorrectos retornadosLa validacion de schema detecta string vs integer
Campos no documentados en responseUsar additionalProperties: false
Valores enum no aplicadosEnviar valores enum invalidos en requests
Formato no validadoEnviar email, fecha, URI malformados

Ejercicio Practico

  1. Lee un spec: Explora el spec de API Petstore en Swagger UI. Identifica todos los endpoints, schemas y campos requeridos.
  2. Escribe un JSON Schema para un objeto producto con: id (integer), name (string, 1-200 chars), price (number, min 0), category (enum), inStock (boolean).
  3. Valida responses: Usa Postman para enviar requests a JSONPlaceholder y escribe tests de validacion de schema para los endpoints /posts y /users.
  4. Encuentra violaciones del spec: Envia datos invalidos intencionalmente y verifica que la API retorne errores de validacion apropiados segun el spec.

Puntos Clave

  • Las especificaciones OpenAPI definen el contrato completo de una API — endpoints, parametros, schemas de request/response y autenticacion
  • JSON Schema provee reglas de validacion (tipos, rangos, patrones, campos requeridos) que mapean directamente a casos de test
  • Cada restriccion del schema genera tanto escenarios de test positivos como negativos
  • Herramientas automatizadas como Schemathesis pueden generar tests completos directamente desde specs OpenAPI
  • La validacion de schema detecta automaticamente incompatibilidades de tipos de datos, campos faltantes y violaciones de contrato