Hey there, everyone that they share.
And in this video, we are going to talk about some of the configuration that you should be worried
about when writing the documentation.
Now, it is very important that you ask from your seniors or somebody who is guiding you that what kind
of versions we are following up in this specification.
For example, writing Swagger 2.0 and writing open API three point something is completely two different
things and you have to follow the documentation and look into the guide for that particular thing.
Now when you write open API 3.0, then whatever the link that I have given to you up here for these
structures, they are actually all for the open API 3.0.
But the moment if you write Swagger 2.0, that means you are following or you are following a little
bit of the older structure.
You need to look the documentation for that.
So it is very important that you write that.
Now again, these are similar versioning.
So as soon as you write 3.0. something or 3.2. whatever the main idea is writing three dot in case you
are using open API.
So let's go ahead and work on with that.
Let's open up our swagger dot yaml.
This is where majority of the time we'll be spending a whole lot of our time.
So let's go up there.
By the way, from the right you can see the swagger file.
So it is really important that you can easily find out that in which file I am working on or I am writing.
And we also don't need too much of this one so we can just go away with that.
So the first thing we are going to write is what kind of open API version we are following.
So obviously we are following 3.00.021 or you write zero.
That is almost kind of a same.
There are very minor differences.
It's not going to break anything.
So that is one thing.
As soon as you do this, you already know that this is how it works on.
As soon as you reload, this is going to say, okay, now you have selected your API version, you know
about it, but you haven't mentioned anything else further.
So the first thing that you'll be writing is the info.
This is all about information.
Make sure you keep an eye on the indentation.
This is super important for it.
The first thing that goes in this is actually the title.
The title define what is this app or this application and what it's going to be using for.
So we'll be using this for is learn, express and swagger.
That's what it is.
And then probably I'll write learn code online.
So this is what we'll be doing up now after that it comes up is the description and I am known for the
typos, but hopefully I didn't meet this time.
So if we're going to simply say that a course segment about writing docs, that sounds great.
Now after that, you can also go ahead and define the version that what kind of version of this documentation
is.
And people really it makes a lot of sense to properly define it and follow some kind of standard with
that.
So we're going to go for 1.0.1 because we have already one gone for the previous one or we can say 1.1.0
because we are modifying it a lot.
But again, make sure you show some consistency up here.
Now, once we are done with that, then comes the two important thing, which is inside this one, which
is contact.
So inside this contact you can write your email so people can actually reach out for that one.
So you always have to write.
It's not compulsory, but you don't have to wrap that around inside the double code or anything.
We are into the segment of YAML.
It is notoriously known for sometimes we use these codes, sometimes we don't.
Majority of the time we don't code.
This is just a specification.
That's why we are here.
Majority of the time you won't be seeing it.
A couple of places are still there where you will find that.
So let's just say if I have an email of I don't have this one, but probably so let's go ahead and use
this one.
And also you can use a URL.
So I'm going to go ahead and use a URL.
Now, in this case, I have to use the double code again.
I'm not making this up.
This is all mentioned in the standards.
So as soon as I do this, this you are going to see that this provides you a little bit of the information.
So this is an Learn Express.
We are following the open API standard three.
This is 1.1.
A whole lot of good information.
You can contact the developer on this website or send the email.
It's up to you.
If you don't want to show up your email totally on you and you can go ahead and skip this part.
Okay.
Moving on.
Now that you know about, these are compulsory things to be done after that comes up is a very interesting
thing, which is servers.
Now, this is something really important for you if you are working in any of the organization, let's
just say I have a couple of servers.
In fact, there are usually more than one production.
There is a testing server sometimes even in between.
So you have to mention all of them.
Let's just say I want to write a setpiece column, slash, slash and I have a local host and Colon 4000
and we are following the standard something like slash API slash V one.
So this is what it is.
And after that we can also write description.
So make sure you pay attention on the indentation that I'm using, otherwise you'll mess it up.
So description we're going to say for local host that's it.
Now notice here very carefully if I go back and hit a reload it.
Gives me this.
My description comes just after this.
And this is all what we have done.
A common mistake that is being done is for the indentation, especially when it comes to this kind of
structure.
People like to go like this.
If you are going to go for this this time, it has given me all these errors thanks to the extensions.
But if it doesn't, make sure you try out your indentation and make sure you stay consistent with that.
Now I'm going to go ahead and select this and I'm going to press my option shift and down arrow key
to duplicate this kind of a shortcut or copy paste, whatever you like.
Maybe I'm supporting the two versions.
One is for HTTP and one is for HTTPS.
This is a dash secure kind of, and this is dash regular.
So these are the two versions that I'm supporting for my API.
If I go back to the browser to reload now, I have a dropdown option of selecting this.
Now I'm not going to be throughout the documentation B following the APIs and these stuff that I'm going
to talk about.
But yes, you can actually go ahead and provide all these options for internal documentation.
But what I like to do more is probably you will be changing this one to V one and V two and this much
of the dropdown sometimes can actually cause like this is too much.
I want to have a little bit more of information now.
Variables are supported in the YAML, but they have a different structure.
So I'm going to go ahead and simply I'll copy this and I'll comment this out.
So Control and Slash are the shortcut for commenting down or you can use the pound sign.
So let's go ahead and use some form of variable.
We don't need this much up here, so we don't need this URL.
Now what happens is that you can first head the tab and you can define your variables like this.
Now in the variables, what we're going to say, you can name your variable whatever you like.
It's up to you.
Make sure you indent it first.
I'm going to first say this is my protocol.
Now you don't need to specifically name it protocol.
You can name it Superman.
But hey, let's make some sense up here.
Now, in the protocol you can define your variables, but I would prefer to have enemies in case you
don't know about enemies.
Enemies actually restrict your options.
Especially I always give the example of airlines.
Airlines always have three options aisle middle and the window seat.
So we want to restrict the options.
In such cases, enemies are the best friend.
Happy here.
Okay, we want to give two options up here.
The first one being this is for version one and the second one being this is going to be for version
two.
Okay, now how I can use this protocol up here.
That is exactly why we have used the double quotes up here.
Variables usually go in the format of this one.
I can go ahead and remove this, remove this V one here because this is the protocol actually this should
be version protocol.
It's going to come up in a second.
So let's change this one to version and I'm going to copy that.
And we are going to remove this, use the curly braces and paste this.
Now, this is version.
Now also what we can do is we can make a copy of this.
So I'm going to go ahead and make a copy of this.
Now, instead of the version, I'm going to say protocol, declare it first or later.
Doesn't really matter.
Now, in this case, I want to restrict the users option to HTTP and I'm going to go ahead and say HTTPS.
Now, obviously, we need to change the protocol up here.
So there we go, just like this.
And we simply go ahead and say protocol.
Now, this is just a bad example that I'm giving you now.
It doesn't say secure or anything because you can go ahead and change this or you can inject your variable.
Another kind of a variable up here that says secure or regular, you can go ahead and do that.
I'll save this one.
Let's go back up here and hit reload.
And you can see that now we have some of the server variables available and you can also mention the
defaults.
We will understand that in the next video.
But right now I want to select the HTTPS.
So my protocol, so this is the computed URL.
And again, I didn't do it so I could actually automatically does all of this and gives me all that
option.
Now I select V two so it gives me v two.
I can go ahead and select v one, it selects v one.
Now I haven't mentioned what should be the default selection.
That's why it's asking me all the time to select one.
But you get the idea that how this is being done.
So this is the basics of how things are being done.
So I told you this is going to be really simple and we are going to understand each and every line of
this documentation.
This is going to be a part of your job, and that's why I'm paying so much of attention on this one.
Okay.
I'll still keep these servers so that you can later on come on to this file and can see at a quick glance
that how things are being done.
That's it for this one.
Next in the next video, we're going to talk about some of the security that you can have for your documentation.
So let's go ahead and catch up in the next video.