-
-
Notifications
You must be signed in to change notification settings - Fork 126
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: add configuration to always show message examples #1016
feat: add configuration to always show message examples #1016
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
@tsauerwein hey, thanks for PR. Can you clarify one thing? so normally examples are always visible, except of this single case with operation? also you mean they are collapsed by default, or not visible at all? with your change, did you try to build this project locally and check in local playground if intended change took place? |
@derberg Thanks for taking the time to reply! Currently, the examples for messages are only shown when the messages are displayed for an operation. If you have a message that is not used in one of the operations, the message is listed in the "Messages" block, but the example for the message is not visible. With this new configuration, the example for the message would be visible: This screenshot was taken from the playground running locally. Also, we have built the library, and are using I hope this makes it a bit clearer. If not, let me know. :) |
@tsauerwein ah that's what you mean. Sorry, I misunderstood the initial message. We need I think a better name for |
side comment, what is the use case for having one message visible in docs, that is not associated with any channel and operation also, can you share how did you make |
Sure, I renamed it to
Let me know if that is clear enough.
We might be abusing AsyncAPI CLI a bit here. But we have a MQTT topic |
We've built it with But |
2bcfa1c
to
e9c5bcc
Compare
@@ -45,7 +46,10 @@ interface ConfigInterface { | |||
- **show?: Partial<ShowConfig>** | |||
|
|||
This field contains configuration responsible for rendering specific parts of the AsyncAPI component. | |||
All except the `sidebar` fields are set to `true` by default. | |||
All except the `sidebar` and `messageExamples` fields are set to `true` by default. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think you meant false
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, the default for sidebar
and messageExamples
is false
. Note the "All except...".
But we could also change it to the following to make it clearer:
The
sidebar
andmessageExamples
fields are set tofalse
by default. The default for all other fields istrue
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, that sounds better, thanks 🙏🏼
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changed
can you please clarify. So because you want to see a message in side bar navigation, you decided to provide message definition only in components, instead under the channel payload? |
@tsauerwein please also look into linter errors btw, thanks for reporting web component release is failing -> #1019 |
Basically, yes. We are using it to document schemas for configurations. So, it means there is one channel/operation and many messages (100+). If we would add each configuration message to the the operation, the message schema would be shown twice, within the operation and then again in the "Messages" sections. Also, the message links in the sidebar take you to the messages in the "Messages" section, where you don't have the example (without the proposed change). And the table-of-content for the messages is quite useful considering the big number of configurations. To give you an idea, this is what the document structure looks like: configurations.yml.txt I would totally understand, if you say that we are using AsyncAPI not in the intended way. But we are using AsyncAPI to document our MQTT topics and like the tooling and the rendered documentation. That's why we also wanted to use AsyncAPI to document the configuration schemas for a single operation. |
|
c616bf1
to
fe7f221
Compare
release fixed: https://github.com/asyncapi/asyncapi-react/actions/runs/9661367651 yeah the problem with how you use it is that messages are not linked with channel and channel specifies only one message, without defining a payload, which means any payload is accepted. It might work for you short term, but what if you'd like to use other AsyncAPI tools - these won't understand the workaround. proper way would be:
I recommend long term focus on using AsyncAPI correct way and just contribute to this component solution that will make side bar messages navigation work in the way, that if Anyway, just sharing an opinion. Not bothering you anymore and playing a smart ass 😄 |
@derberg Thanks for fixing the release! And thanks for the feedback, you are absolutely right. The "Test NodeJS PR - ubuntu-latest" job has failed. Could it be that package.json and package-lock.json are out-of-sync on |
Working on it. For some reason bump of react component in web component did not work as expected. |
fix is up #1026 |
Thanks! I will rebase as soon as the fix is merged. |
|
99fc765
to
2becbd9
Compare
|
/rtm |
🎉 This PR is included in version 2.1.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
Thanks for the review and making the release, @derberg! 🚀 |
Description
Changes proposed in this pull request:
show.messageExamples
, which whentrue
also shows examples for the messages in theMessages
section (and not only for the messages in the "Operations" section).Background:
Maybe we are using the AsyncAPI CLI not in the intended way. But we have messages that are not referenced in one of the operations, so that the examples for these messages are not visible. This PR is proposing to add a new configuration, which will show examples for the messages listed in the "Messages" section.
Related issue(s)