Te sugerimos que revises esta respuesta en un ambiente controlado antes de pasarlo a producción, saludos.
Solución:
La especificación OpenAPI/Swagger solo puede admitir la definición de esquemas y, por lo tanto, sería útil para definir eventos en un sistema controlado por eventos. Dichas definiciones también pueden ser utilizadas por herramientas de generación de código como OpenAPI Generator para crear automáticamente objetos de esquema para lenguajes como Java, Swift, Go, etc.
Al diseñar esquemas de eventos, es útil evitar el polimorfismo. Si bien la especificación OpenAPI 3.0 ahora admite tales definiciones, las herramientas aún son limitadas.
API abierta 3.0
Con OpenAPI Spec 3.0, puede admitir múltiples tipos de eventos en una definición usando su oneOf, anyOf, allOf apoyo. Hay más información en los documentos de OpenAPI 3.0 aquí:
- https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
Todavía no he experimentado con esto porque la especificación OpenAPI 3.0 aún no es compatible con Swagger Codegen for Go. Sin embargo, están trabajando activamente en Java, por lo que si ese es su idioma de elección, puede intentarlo.
Puede seguir el soporte de Swagger Codgen para la especificación OpenAPI 3.0 en este número de GitHub:
- https://github.com/swagger-api/swagger-codegen/issues/4669
API abierta/Swagger 2.0
Para Swagger Spec 2.0 (también conocido como OpenAPI Spec 2.0), puede incluir definiciones en la especificación Swagger como lo menciona alamar. Swagger Codegen creará automáticamente clases modelo para estas definiciones, incluso si no están asociadas con ninguna ruta. Construyo y mantengo un SDK creado con Swagger Spec/Codegen en Go para la API de RingCentral que tiene eventos como este. Puede ver las clases/estructuras generadas automáticamente que Swagger Codegen construye en la siguiente carpeta, filtrando los 20 archivos que terminan en _event.go. Estos se crean actualmente usando swagger-codegen 2.3.1.
- Archivos generados: https://github.com/grokify/go-ringcentral/tree/master/client
- Información de Codegen: https://github.com/grokify/go-ringcentral/tree/master/codegen
Si tiene varios tipos de eventos, tener una propiedad de evento que pueda distinguir los tipos de mensajes que está recibiendo puede ayudarlo a analizarlo en la clase/estructura de evento correcta. En Go, puede ordenar los datos dos veces, una vez en una estructura genérica para ver la propiedad del tipo de evento y luego una segunda vez para el tipo de evento real.
También mantengo una colección de eventos de ejemplo y código de análisis en el proyecto reformateador de webhook de Chathooks que puede usar como referencia. Puede ver los eventos de ejemplo y las definiciones de idioma (a mano) aquí:
- Ejemplos: https://github.com/grokify/chathooks/tree/master/docs/handlers
- Definiciones: https://github.com/grokify/chathooks/tree/master/src/handlers
Creo que puede tener definiciones en Swagger incluso si no son utilizadas por ningún punto final. Simplemente declare cualquier tipo que necesite en una sección dedicada, por ejemplo, “definiciones”. Puede hacer referencia a los que está utilizando en los puntos finales como, por ejemplo "$ref": "#/definitions/User"según el ejemplo principal de Swagger en vivo.
Espero que se genere código para ellos, por lo que puede escribir pruebas contra cualquiera de las definiciones.