# Openapi Asyncapi Contracts

> Definir y versionar contratos de interfaz entre agentes REST (OpenAPI) y asíncronos (AsyncAPI)

- Skill: `davidcastagnetoa/openapi-asyncapi-contracts` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add davidcastagnetoa/openapi-asyncapi-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davidcastagnetoa/openapi-asyncapi-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: davidcastagnetoa (https://skillmd.com/u/davidcastagnetoa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davidcastagnetoa/openapi-asyncapi-contracts

---


# openapi_asyncapi_contracts

Los contratos entre agentes definen los schemas de datos que cada agente acepta y produce. Son la fuente única de verdad para comunicación inter-agente y previenen breaking changes.

## When to use

Usar para documentar y versionar todos los contratos entre agentes: endpoints REST, payloads de Celery y eventos de auditoría.

## Instructions

1. FastAPI genera OpenAPI automáticamente en `/openapi.json`; verificar que está completo y correcto.
2. Versionar el `openapi.json` en Git: comparar con la versión anterior en cada PR.
3. Para mensajes asíncronos de Celery, definir contratos en AsyncAPI 2.x:
   - Crear `asyncapi.yaml` en `docs/contracts/`.
   - Documentar cada canal (cola Celery) con su schema de mensaje.
4. Implementar un breaking change detector en CI:
   - `pip install openapi-spec-validator oasdiff`.
   - `oasdiff breaking old_spec.yaml new_spec.yaml` → falla el CI si hay breaking changes.
5. Usar Pydantic models como fuente única de verdad y generar los specs desde el código.

## Notes

- AsyncAPI playground: https://studio.asyncapi.com
- `oasdiff`: https://github.com/Tufin/oasdiff — detección de breaking changes en CI.