API Swagger

• Visor interactivo (Swagger UI): abrir
• Contrato fuente (YAML): openapi.yaml

Pruebas de autenticacion con cookies

• swagger.html esta configurado con withCredentials: true.
• Para probar login/refresh/logout por cookie, el API debe permitir credenciales en CORS (Access-Control-Allow-Credentials: true) y origen explicito (sin *).
• POST /api/v1/auth/logout acepta cookie accessToken como via principal y mantiene Authorization: Bearer como fallback de compatibilidad.

Nota de arquitectura (Clean): Los DTOs de este contrato corresponden a la capa interfaces/http; los use cases viven en application y las entidades de dominio no se exponen. Handlers mapean DTOs ↔ use cases y usan repos (interfaces) definidos en dominio/aplicación.

Fuente única: El contrato se mantiene en static/openapi.yaml (diseño-first). Evitar duplicar en otras carpetas.

Convención terminológica: en producto usamos "Profesional de la Salud" y "Entidad de Salud"; en API/código se conserva el alias técnico DOCTOR (/api/v1/doctors, doctor_profiles) por compatibilidad.

Scope freeze de inicio (Registro/Auth): ver 32-contratos-registro-autenticacion-v1.md.

Ciclo de vida del contrato (versionado y deprecacion)

Politica de versionado API

• El prefijo de ruta se mantiene en /api/v1.
• Cambios no compatibles no se liberan en caliente sobre v1; se planifica nueva version (/api/v2) con plan de migracion.
• Cambios compatibles (campos opcionales, nuevos endpoints, nuevos codigos) actualizan info.version en openapi.yaml con semver.

Politica de deprecacion

• Todo endpoint en deprecacion debe marcar deprecated: true en OpenAPI.
• Se agrega cabecera Sunset en respuestas del endpoint deprecado.
• Se documenta reemplazo recomendado en description y en changelog de docs.
• Ventana minima de deprecacion: 90 dias antes de retiro en produccion.
• Formato oficial del changelog: ver 14-release-changelog.md.

Regla de breaking changes

• No remover ni renombrar campos en respuestas de v1.
• No cambiar significado de enums existentes.
• Si se requiere romper contrato: crear endpoint nuevo y mantener compatibilidad temporal.

Catalogo canonico de errores API

Todos los modulos deben reutilizar este catalogo. Se expone en Swagger y se referencia desde Registro/Autenticacion.

Codigo	HTTP	Retryable	Uso esperado
BAD_REQUEST	400	No	Payload invalido o faltante
UNAUTHORIZED	401	No	Token ausente/invalido/expirado
FORBIDDEN	403	No	Rol o scope insuficiente
NOT_FOUND	404	No	Recurso inexistente
CONFLICT	409	No	Duplicidad o estado conflictivo
VALIDATION_ERROR	422	No	Reglas de validacion de dominio
RATE_LIMITED	429	Si	Exceso de intentos
INTERNAL_ERROR	500	Si	Error no controlado
UPSTREAM_ERROR	502	Si	Falla de proveedor externo

Formato de error estandar:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Datos de entrada invalidos",
    "details": [
      {
        "field": "email",
        "reason": "invalid_format"
      }
    ],
    "trace_id": "2d0bcf2c-3e87-4f97-95a1-c25b95bf760a",
    "retryable": false
  }
}