search

swagger-api / swagger-core

Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API
http://swagger.io
Apache License 2.0
7.37k stars 2.17k forks source link

[discussion] Is swagger right place to define asynchronous interfaces? #2512

Closed archenroot closed 6 years ago

archenroot commented 6 years ago

In our microservices architecture REST API servers "only" for:

On the other hand, whole architecture follows sagas, event sourcing, cqrs patterns, but I lack a tool for these interfaces similar to swagger. In REST only design swagger shines, but microservices are going to be async by design, and in that case I am missing some unified approach to document both sync and sync under single hood...

Do you plan to support something like this? Or you think it is bad place, so swagger=rest only? Or is there other product which joins sync and async worlds?

I think there is no such think in the moment.

webron commented 6 years ago

REST does not mean synchronous only. Asynchronous APIs are supported in OpenAPI 3.0 through webhooks and callbacks. Whether your API is designed that way is a different thing.

An event-driven API is something that's not directly supported by the spec. We're having discussions on it, but it's out of scope for this project.

archenroot commented 6 years ago

@webron - thank you very much, it is actually as I expected...

Actually the more I work on design, the more I am completely getting rid of any kind of REST, the only remaining REST user was UI service, but I am now i working on POC where UI service will be also completely async...so...

archenroot commented 6 years ago

Just to add something. In pure event driven architecture there is even nothing like async response/callback. There exists only series of events. When you dive deeply into this, even the CQRS pattern is not something what should be exposed to any client or service.

It is only sequence of:

1 - A did this -> let the world know 2 - B listen to what A did -> B does function on what A did -> let the world know 3 - C listen to what B did > C does function on what B did -> let the world know nothing like async response/callback...

The more I think about pure async event arch, it is not about API at all, it is like history processing, where one event is implemented completely independently.

The real binding things together is actually the definition of event chain in so called event storming sessions and required sharing DTO. What event-driven architecture implemented with UI together brings to the world is merged platform of middleware with BPM engine together (all is stateless including UI, but event sourcing serves as process sequence tracker and replayer if required..).

The current microservice architectures I read on internet or books are all kind of mixture of what happend(pure history event) and of what I ask to happen(commands) and in large scale this is creating confusion (I don't talk about fact that symbols like CRUD should be completely removed). If I talk about event driven, there is no space for what will happen, or what I ask to happen, no request, async response/callbacks, it is simply only about what happened and if I am interested use this information, end of story :-))

I will write some blog about this...