search

asyncapi / html-template

HTML template for AsyncAPI Generator. Use it to generate a static docs. It is using AsyncAPI React component under the hood.
65 stars 59 forks source link

[Feature request] Make generator html/markdown support bindings #25

Closed derberg closed 3 years ago

derberg commented 4 years ago

@karlwbrown commented on Mon Dec 09 2019

Currently, any bindings provided seem to be left out of the HTML/Markdown.

Even if we aren't doing any validation on them, it would be valuable IMO to have the HTML/Markdown include these bindings, specified as such and basically copied as-is from the schema.

This way, if you specify some bindings in your schema definition, anyone reading those API documents will be able to see those.

In the future this could be made more sophisticated, but just pushing them out in some reasonable form would add value as a start.

@damaru-inc commented on Wed Dec 11 2019

I would also like to see this. For the Solace template I'm writing, bindings are essential.

@jonaslagoni commented on Wed Dec 11 2019

Yea, I agree this would be useful. Maybe we could reuse the implementation from https://github.com/asyncapi/generator/issues/136. Also since the bindings are far from stable I think this could be a suitable solution to this issue, what do you think?

@fmvilas commented on Sun Dec 15 2019

👍 to @jonaslagoni suggestion. Seems like a suitable solution meanwhile bindings get stable.

@derberg commented on Wed Feb 19 2020

Looks like a perfect issue for me to start with templating and having a need to understand bindings? Anyone working on it already, or can I pick it up?

@fmvilas commented on Wed Feb 19 2020

I'd not work on this issue yet. Bindings specs are really unstable yet. Maybe this one is better as your next one: https://github.com/asyncapi/generator/issues/182.

@derberg commented on Wed Feb 19 2020

sure thing, I thought about this one as an alternative temp solution was suggested, but #182 is also fine

@github-actions[bot] commented on Wed May 13 2020

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

github-actions[bot] commented 4 years ago

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

mekras commented 4 years ago

This issue is still actual.

github-actions[bot] commented 4 years ago

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

github-actions[bot] commented 3 years ago

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

github-actions[bot] commented 3 years ago

This issue has been automatically marked as stale because it has not had recent activity :sleeping: 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 :heart:

M3lkior commented 3 years ago

Hi @derberg i can partially help on this issue by handling the message bindings which i think is the most important part to display for a start

I think that we can reuse schema macro approach to display messages bindings in the same block like 

   {{ schema(msg.bindings(), 'Bindings', open=open) }}

In my enterprise case, i need to display to my users my kafka message key and i think this is the right place to do that : image

What do you think about that ?

derberg commented 3 years ago

I think doing it first for message is a good idea. Did you try schema macro already or what you showed above is just a mock? This macro is for rendering schema, while what you get in the binding is not a schema so I'm not sure how is it going to work, you need to see. I think that as suggested by @jonaslagoni, the only way, for now, would be to reuse the approach for spec extensions https://github.com/asyncapi/html-template/blob/master/partials/schema-prop.html#L159-L198

I'm not sure Bindings is a good heading. This is a name that was chosen for the specification but the reader of docs doesn't have to know what that means. Shouldn't it be something like Protocol bindings or even Protocol-specific information?

I'm also thinking if bindingVersion should not be hidden from user's sight 🤔

M3lkior commented 3 years ago

What i show above is just a mock for now to enrich the discussion ...

Although I'm not sure that the msg.bindings() exists ... i don't find the place where the generator api is described, can you share me the place to find this information ?

I agree with you about the Binding header, but it was just for the example How do you think about displaying the protocol attribute (kafka or mqtt for example) thanks to a colored label like this ? image So the header should be Protocol-specific information with the associated label ; and can be multiple if multiple message bindings are specified ; even if it is a weird specification approach.

derberg commented 3 years ago

@M3lkior sorry for late response, I totally missed your comment

Generator uses Parser to parse the document and provide an API to read its content, API docs are here https://github.com/asyncapi/parser-js/blob/master/API.md

you have msg.hasBindings() and msg.bindings() and others:

.hasBindings() ⇒ boolean
.bindings() ⇒ Object
.bindingProtocols() ⇒ Array.<string>
.hasBinding(name) ⇒ boolean
.binding(name) ⇒ Object | null
asyncapi-bot commented 3 years ago

:tada: This issue has been resolved in version 0.19.0 :tada:

The release is available on:

Your semantic-release bot :package::rocket:

derberg commented 3 years ago

@karlwbrown @mekras @damaru-inc thanks to @M3lkior you can now get bindings info in generated HTML using the latest version. Please also keep in mind that for few weeks it is also possible with the react component

derberg commented 3 years ago

@M3lkior would be great if you could bump HTML template in https://github.com/asyncapi/playground as this part is not automated yet

M3lkior commented 3 years ago

@M3lkior would be great if you could bump HTML template in https://github.com/asyncapi/playground as this part is not automated yet

Ok @derberg, with pleasure ; I will also do a PR for the markdown template