AsyncAPI Hacktoberfest Office Hours, 20 Oct 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: #Hacktoberfest Office Hours - 20.10

Description

Read more https://www.asyncapi.com/blog/hacktoberfest-2020

A

Hey um we're live so welcome.

A

It's lukas from asking api um initiative. We have our another live stream for hacktable, first participants, but of course, if not many people will join, then um you can of co. I don't think we have any viewers.

A

Okay, we have first viewer.

A

um Give me a second because I just got a question on.

A

A

Just a second, I have to let my dog out, so I don't have to clean after una.

A

A

So before we start.

A

I'm gonna come on.

A

I wanna test out because I love when I do stuff. I love to listen to the music, so I want to try out if I can play.

A

The music in my ass headphones and that you also can hear it okay, so we have already onto this um here so huge requests. I'm gonna try out now to like play the music and please let me know in the comments if you can hear it so I know it works.

B

A

A

Okay, now I can hear the music.

A

Okay, so underneath antoneth, I just started playing music in my headphones.

A

And please confirm if you can hear it on your side.

A

Okay, so just a.

A

A

How about now, can you hear it.

A

Okay, but you can hear me speaking right still.

A

Okay, cool, that's good.

C

C

C

C

D

D

D

D

D

B

B

B

A

A

Okay, so let's let's leave it, um I'm not gonna play with it now, because I'm just gonna take your time um I'll, try to figure it out figure it out later. um If there are no questions, um oh okay, so before antoinette uh before we jump into your questions, let me just um uh summarize so we have 20th of october two weeks left till the end of the october fest.

A

And we have 24 contributors so far on the oktoberfest and 57 pull request merged, which is awesome um but yeah. Let's, um let's look into the comment section, because there are many uh many questions I think from unto death.

A

um Okay, so the question is to a hacktoberfest issue about the parameters in the html template um and the question is, let me show it on the stream. I don't understand how you pass the parameters to the template. I mean if I want to pass description, can I do it like this.

A

A

So let me answer by just showing the sharing the screen um dum dum.

A

A

A

Let me just um turn on yeah it's the last time. I have only one monitor.

A

So I have to yeah watch the stream on my on twitter on my mobile.

A

Sorry for that, because this way I can see if there are some additional questions, otherwise I cannot see them um yes, so um the questions come to this issue, so the issue title is parameter. Doesn't description does not render in resulting output with html template?

A

What is it about in detail? So the um let me show some awesome api file.

A

A

So when an async api file you can have, you can define a list of channels um and channels can have parameters so those special values, let me make it bigger yeah, so can have parameters so those special values in between the mustache and you can describe those parameters later in a parameters object.

A

So you can see the mapping right straight lights, id street lights switch, light street light id and let's see, parameters.

A

Object here, okay- and you can see that you can, according to the spec, you can provide a description, human readable description of the parameter. What it's for and the problem, the bug that is reported here is that this description is not rendered.

A

So, even though I provide description here, it will not be rendered in the ui.

A

So let's check it out. First in our playground,.

A

Okay, it's the same street lights example here, so we have this parameter. Streetlight id.

A

Which is here, then we have those parameters described.

A

And it says streetlight id and it only says that it is a string, but it does not display the description of the parameter.

A

So this bug is true. First of all, and let's go further into the notes I provided for for the.

A

Issue, and give me a second break.

A

Okay, a coughing break.

A

Okay, so in the issue, what I did, what did I do here? Okay, so the first link, it's a link to a place where the logic is for this displaying the the parameter.

A

Let's double check so uh typical.

A

Typical investigation of the.

A

In the browser.

A

So it says, span.

A

But what about the this component.

A

Okay, so it's a children background. Let's see if I point it out properly: yeah children, background gray,.

A

Light is, let's make sure, that's the stuff yeah exactly.

A

um So here, as you can see what we're doing so, we are rendering a div element and we're templating um we're treating parameters. Let's say as a we're. Iterating over the parameters, objects.

A

A

To render them, we treat them as.

A

We pass the schema parameter.

A

Schema the the schema of the parameter to schema prop uh to schema prop um macro and that's the second link I shared so a macro. The schema prop macro. In short, what macros are so? These are like javascript functions, let's say so. um It's like reusable template that accepts um arguments.

A

um So basically, whenever in this templates uh template the schema prop is called the schema prop macro with the following parameters, then this is going to be rendered basing on the parameters passed to this um to this macro.

A

So I think the background is pretty much clear and now, looking again on the question, um how you pass parameters to the template, I mean, if I want to pass description, can I do it like?

A

Okay now the question.

A

Makes a lot of sense? Because the question is about.

A

As you can see here, parameter description will never be used because we are explicitly passing only the parameter schema. So looking again on a street lights example.

A

You can see that schema is on the same level as description. So if we're passing parameter schema, then the description.

A

uh Then the schema prop macro just has no access to this description. It's just gonna. Take the um the description from the from the schema. If it's provided in the schema.

A

Now how to solve it, the easiest would be just to pass um like uh like at the end, let's say, extend the extent the the macro pass, parameter, dot, description and then consume it here. Right so add it to this macro and then yeah add it to the template.

A

But I'm thinking if it's.

A

If it's, if it makes sense, because at the end, this this macro is purely designed to to render uh the schema and parameter description, it's not part of the schema. So that's a.

A

um At current shape of the macro, that's pretty that's not the best approach, so you can see here.

A

Here, for example, in the template, how the payload, for example, lumens humans- where is it yeah?

A

So you see schemas.

B

A

So you can see and if a description is provided on a schema level.

A

Then it's rendered so just look. What's gonna happen to the parameters, if I add a description.

A

B

A

A

So the description added on a schema level got rendered.

A

Which is fine, I say a kind of fallback, but instead of this is my test.

A

We should get this and now I'm thinking about overriding the value.

A

So unto death, I'm.

A

I'm thinking how bad would it be if, if, before passing the schema, the parameter schema.

A

We would first add a description to it if it's, if it's provided on in the parameter.

A

So I'm now thinking out loud, but so what what I'm? What I'm saying is basically have a um in between 44 and 45 have a logic that checks if, if parameter dot, description returns something, and if this description is returned, then it should be added to parameter schema.

A

The only problem is that it means that we are kind of mutating mutating. The schema in the template.

A

Which is not the the coolest thing to do.

A

Kind of ugly, I would.

B

A

I mean we could now when I'm thinking about this schema prop, let's see, let me see if there are any questions.

A

uh If not a default parameter and you are passing it.

A

um I didn't get, is it a question.

A

I didn't get, it didn't get it. So, if you could rephrase the.

B

Question would be awesome.

B

A

Okay, let me you know what let me open it up.

A

um Okay, I'm not.

A

Sharing, let me open up codebase.

A

A

Okay, let me share screen.

B

A

I'm gonna try to make it bigger.

B

Okay, I think it looks good.

A

Okay, so I'm on the latest html.

A

Template, let's get some.

A

A

A

Okay, I didn't use it uh quite some time ago. Okay, so let it uh download chromium for the first time but yeah. Let me jump to the schema probe.

A

It was in schema prop and what was the other file operations was.

B

A

A

A

Parameter schema exactly this.

A

A

Okay, so what we're passing here is the schema name and then three.

B

D

A

I'm thinking how.

A

How much would we break.

A

How much would it we break it?

A

So if it's alternative description, if we would add.

A

Something like this.

A

How much would it break.

A

A

Now and that's the location where we take out the.

A

A

So if description is provided, we render it.

A

Okay, we allow markdown in descriptions of course, so it's here.

A

We could do something.

B

B

A

The basic installation completed.

A

A

Okay, so we have it, of course, without description.

A

A

So if schema has description then render it, but I would I would like, but I would like.

A

To treat the alternative description as.

A

A

This would be as full back yeah. I know it's a code, dopply kind of code, application.

A

In theory, it should work.

B

A

B

A

So we are sending the parameter description and if it's provided it will, it will be rendered.

A

Let's see if nothing fails.

A

B

See was it this.

A

Exactly I, the idea of this street light.

A

So, let's, let's have a look if I.

A

A

A

Let me create locally asynchron.

A

File think rpm file.

A

And no actually not this one. Let's take.

A

The dummy example.

A

The dummy example and see for some parameter okay, so we have the id of the dummy message and let's extend it with.

A

A

Description that should not be.

A

A

Okay, now, if I fire like fire start generation, it should generate html, where we will see only this description.

A

Okay, let's see.

A

Parameter dummy the idea of the dummy message, which is awesome.

A

And the template behaves without any.

A

A

Circular references, if detected, they are still displayed properly.

A

I would say we have a solution.

A

um So antoneth are you? Are you still there with me.

A

Okay cool, so let me like go through step by step. The the solution, um like I say, kind of summary, what I've done and then shoot me with questions.

A

A

A

Yeah I kind of kind of yeah, but I will not push.

B

A

A

So basically, the schema prop macro had to be extended with something I mean. The the name of the of the argument can be changed. I thought that might maybe not out. Alt is like for alternative, probably better. If it's odd tests.

A

Something like this, and by default, it's always null.

A

Unless you explicitly, whenever you use it, unless you explicitly.

A

um Pass a description to it now, what happens if description is is not provided then it's I mean. Basically, it's not a problem, uh because if description is not provided, let's see in the api.

A

So the template, all those things as you can see in the template like.

A

Parameter.Description function or or schema function. It's all part. um It's all there because.

A

When we take async async document, we parse it with our async api, javascript parser and as a result of the of the parsing, we give you a um a object with a lot of helper functions that make it much easier for you to access parts of the async api document.

A

So you don't have to access it like a usual like json, uh but you have those um nifty functions available and you can always consult with the api of the parser.js.

A

So you, basically all the models that you have access to are in the parts of js in leap in models.

A

Let's take a look on the uh on the operation because parameter is no parameter is not part of the operation. It's part of the.

A

Channel parameter, there's a separate model for it.

A

Or it's not a channel.

A

Parameter channel parameter mixin.

A

Description mixing description: let's go into the mixing description. Okay, those mixins! That's a pretty nifty solution. It allows us to simply have less code.

A

uh These are like um mixes, are a way of extending uh the models in a nice way with um functions that are used across the model, uh the different models so description, it's a function that is used um in many different uh locations of the spec. So that's why it's better to have one mix in and then yeah extend model with this mixing.

A

So get so we're getting the.

A

Get marked value by key.

A

So we're passing the parameter go on.

B

Description if it's.

A

So if object, if key for it's, not it's string, then.

A

If, if okay, if it's undefined and will return null, okay, that's cool, so basically from this implementation, we know that, uh if description will not be there, it really, as it stated in the in the js doc, it will return null, which is fine, which means that in this particular case we do not need to use this test description function.

A

um So we do not have to do any ifs. If description is provided, then pass this description, because, anyway, what we're doing here in schema prop, where anywhere in a way prepared that alt description, alternative description can be null.

A

And then this alternative description is.

A

Of course consumed here, so we we make alt description as a primary, but if it's not here, then we check um else. If, if maybe this schema has a description and then we are rendering.

A

A

Yeah and that's.

A

That's about it and underneath when you will work on the pull request, what you could do and it's something that I did not do in this pull request.

A

As you can see here, and here we have basically the same the same code.

A

Just different value is passed to the template, so this could be um taken into a separate file and we could have a a macro just like the schema html file. So you would create a separate file called description, dot html in and in this in this new file.

A

You would have just this line.

A

But that part that part would be the name would be something that you would have here, so you would have. So let me just summarize, so you would create a a description.html file in which you would have to create a new macro like reusable template.

A

A new macro called uh get description, and this this new macro get description would accept a a argument like called description right.

A

So it would looks like something like like this.

A

So later on, in schema prop html.

A

Instead of having this, you would do.

A

Get description.

B

A

See so that would be.

A

That would be the ultimate the ultimate.

A

Goal you even you can even see that this this schema prop macro. It also uses some um some external macros, so adding additional.

A

Like description, import get, you would do something like this and in this description, dot, html file, you would have this. The single div element.

A

And you can see here, for example, how this is used. ah Yeah, of course,.

A

It's a template, so yeah you would have to do something like this.

A

So, instead of duplicating the same div element.

A

You just have it once in the macro and then you would use it as a regular javascript function inside the template.

A

So something like.

A

B

A

um Now that would be a good moment if you could confirm if that makes.

A

A

A

Yeah, it's so at the end, it's up to you, how you name it um so. Basically it's um we somehow need to to name this variable.

A

So it's because we know it's a alternative description and I'm calling it alternative description, because this particular macro is responsible for rendering this schema and schema has its own description. So everything different. It's like alternative for me.

A

So that's why I call it out alt description or late dsc like desk alt desk, um but it can be called even long name like alternative description, but um all alternative desk. Maybe this one is better.

A

Yeah just just be consistent and make sure that you use the same name everywhere now.

A

Okay and then, like I said, the macro would have to be created to not duplicate the html.

A

Code and extra stuff, if you could, that would be great. um So the the rule that we're following here when we're when we're working on templates is that we.

A

We're working on this dummy, let me share screen.

A

Again, we work on this dummy.

A

Dummy asanga asang apim file.

A

uh Let me show it to you.

A

Okay, here it is um so we let me make it bigger, so we basically we did not want to abuse the streetlight example too much because we noticed that we have like every template has its own version of streetlight example. So we are thinking like yeah. Let's make a a single dummy example that will not be will not serve as a an example for the community to to um to see how async api file should look like.

A

So for us, this dummy example it's something that we can abuse we can call over complicate, but the goal is to have a as feature rich example as possible, meaning we want to present as many features as we can in the single document. So it's much easier to develop templates to to have sample data for developing templates, because the schema you can imagine there are different variations of of things. You can do um so yeah.

A

The idea is that we could maybe have one single document where we have all the all the different use cases so far. It works and what I would like to ask you to do once you're done with your uh with your pull request for the parameters.

A

Please please, please, if you can create, also a pull request here to the generator repository and extend suggest in your pull request that this dummy yum file.

A

Should have an example uh that you don't only have a description.

A

Next to schema, but that you also have description for the schema, so you already have a use case here that there can be a description provided for the parameter and inside the schema. So when I work on the template- and I know which one should I treat this primary.

A

A

A

A

Oh, so we are pretty much done.

A

A few minutes left, so let me um if you can stay longer a bit to be my voice. Tester. That would be awesome. um I wanna make sure that I can stream the music as well. So I'm gonna now play with the settings. If you don't.

A

C

C

A

Okay, you can hear me, but not the.

A

A

Can you hear me now.

A

Okay, still, no.

A

A

C

C

C

A

Okay, again voice only where's, the music.

B

B

A

A

Okay, um so antoinette.

A

Let me let me share again.

A

A

So the thing is that we.

A

To make it easier for templated developers to work on on features for the templates we whenever we we work on some feature, and we see that this dummy example is missing, something we had to explicitly add something.

A

Then we should always update this original dummy file in the generator repository. So you could see.

A

That, for example,.

A

For example, here when I wanted to somehow make sure that the schema description is not rendered and only the main description is rendered, I had to extend dummy example manually with this manually with this additional description, which was fine for local development. That was fine. I um I finished the work, that's it, but.

A

But our readme thanks to barbara.

A

B

B

B

A

Okay, I need to check something later. It looks super strange.

B

Wait wait, wait, wait, wait.

A

Okay, so for now never mind so anyway, my request is, if you could add.

A

This description.

A

To this file, in the generator repository.

A

Here to this dummy parameter, that would be awesome.

A

Yeah exactly extend.

A

Extend the dummy yum file by adding this additional description to the schema of the parameter.

A

Okay, let me now confirm, because I'm pretty sure that barbara made a contribution.

A

To the html template.

A

A

A

Which makes it super strange why I cannot see it on my local, what the heck just happened, but yeah anyway, um if you go to the latest html, you see this information about a dummy yam file in the readme in the development section.

A

Okay, so let me go back to.

A

uh Exploring the sound settings.

A

And I'm gonna move the stream.

A

Window to my desktop, so I can see if you have some questions that I can follow up.

A

B

A

A

Okay, so I basically what I'm doing now, I'm using sound flower.

A

And in the audio devices settings I am able to send output into two different devices: the jabra and.

A

B

Test test test.

C

B

B

B

B

B

B

Writing's not that easy, but grammarly can help. This sentence is grammatically.

A

B

B

A

Okay, so I have some flower.

A

A

A

Is it something in the stream yard that I can set.

A

Oh, maybe it's this.

A

A

Can you hear.

C

A

That is awesome now I can do live streams all day, long.

A

That's cool, that's so cool, I'm! So super happy.

A

Yeah, exactly like, with every stream step by step, we're getting better and I'm liking it even more. Every stream, but now with music.

C

A

Okay, but anyway, there's this saying in polish, we say um fist cuts, which basically means.

A

The good things at some point of time have to finish like have to end, and it's the same with this stream.

A

We have to finish it so antonette. It was a pleasure if you have any questions or follow-ups.

A

Feel free to ask.

A

A