operationId usability in code generation

[derberg]

tl;dr we need a way to provide operationId for code generation of different applications, both server and clients, or in other words consumers and producers. So there is a need for different operationId names depending on the "perspective" or let's simply call it the "purpose of generated code"

Currently, AsyncAPI document should be written from the perspective of the "client", the user that interacts with described API.

This perspective causes for example a confusion around the understanding of pub/sub semantics

Another challenge with having only one "perspective" is around the operationId.

Let's take the following part of AsyncAPI document:

/travel/status:
    subscribe:
        summary: You can listen to travel info status.
        operationId: onTravelInfo #client code perspective, generated client reacts "onTravelInfo" incomming message 
        message:
           $ref: '#/components/messages/travelInfo'

The client, the user subscribes to /travel/status. The generated code gets a function onTravelInfo, that reacts on incoming travel info. Sounds good, right?

Challenge is that I want to not only generate a code for the client, but also the server, the server that exposed the API described with AsyncAPI document. What shall I do with operationId. I either rename to to something like subTravelInfo which is neutral, but not super clear about the purpose and will make my generated code cryptic. I could also just rename it to sendTravelInfo but then have a situation that I do not follow the AsyncAPI approach to describe API from client perspective, make things even more confusing.

[fmvilas]

Same problem exists with the summary and description fields. A description that is best suited for "clients" doesn't fit well when documenting your "application". It's a mess. And it's all caused by the mess with publish/subscribe. I think once it's fixed there it will be automatically fixed here too. Especially, if we split verbs into the two categories/point of view.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[fmvilas]

I think in v3 we should require one document for the client and another one for the server. In other words, we don't allow deriving one from the other. So you can't figure out the client by just switching send and receive from the "server" document to get the client one.

It needs a PR though. @derberg I'll be happy to take it if you're not in the mood.

[derberg]

@fmvilas be my guest ☺️

[fmvilas]

Done #875

[asyncapi-bot]

🎉 This issue has been resolved in version 3.0.0-next-major-spec.8 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[fmvilas]

Calm down, almighty bot, calm down.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️