Hey there, everyone here.
And welcome to another video.
And in this video, we're going to write our very first basic swagger documentation.
So the way how we write the swagger documentation is, of course, we all the time keep open up this
basic structure link.
This helps us to get a lot of documentation as well as some of the prototypes and all of that, because
remembering all of them is really a tough thing and nobody remembers, especially the documentation
and the syntax of it.
Eventually you learn a few things over the time, but nobody remembers all of this.
So we keep this one as open up all the time.
And next come up is how you want to structure your documentation.
Whether you want to keep it into a separate file, you want to write them on the go and every route.
So how you want to do it, that is all it's going to depend on this.
Let me walk you through with both the path and I'll walk you through that.
What we are going to opt in this case.
But again, there is no wrong or right here.
It just is your preference.
Now, obviously, whatever you do, the swagger UI express is one of the thing which you will obviously
install.
So make sure this is one there.
Now, apart from this, you are also going to notice that some people like to use a different package
alongside with Swagger UI Express and that is Swagger Dash JS Docs and this doc so.
DZ Doc now what you can do is you have to decide that whether you are going to write things on the go
or you will write them into a separate file.
Let me bring up the VS code that has opened up our project already.
So this is the one.
So what happens in some of the cases is if you don't prefer to write your documentation in a separate
file, which is usually the recommended way, but in some cases it makes sense to have the documentation
just above this route.
So whenever you are defining these routes, whether into a separate file or disappear, people actually
come up and write the documentation is here.
How we do that, we put up a slash and two instances.
As soon as you do this, the ending will be there and now you can just use these things.
So you can simply say this.
Let me just walk you through without writing that.
So you can go ahead and simply say, add the rate open API, or you can write swagger here as well and
you can then start writing all of this.
Now what this all is, we will definitely discuss this, but the whole idea is you can go ahead and
simply say open API or swagger and you can start writing a documentation in here.
You can define that this route is going to be slash Facebook and all of that and then start writing
the get post and all these requests.
In case you want to do that, then obviously you have to install this package also, which is the swagger.
JS Doc, now we will not be doing this because in this case I want you to take one step further and
I want you to install less packages and write your documentation into a separate dedicated file, which
makes much more sense in longer run.
So we'll be going with just in the Swagger UI Express.
So let's go ahead and install this one.
So we're going to copy this one and we need just this package, at least as of now, we'll be needing
one more.
So let's go ahead and simply go ahead and install the Swagger UI Express.
Let's go ahead and install this again, a very teeny tiny package, but really, really powerful.
Let's see.
Okay, so this has installed swagger UI Express.
We are all happy.
Okay.
Moving on in the documentation.
So we have installed it now.
Obviously we need swagger.
So we're going to go ahead and borrow this line up here.
And these two these three lines, actually, we need all three of them and let's dissect them so that
we can understand them fully.
And I'm going to also go ahead and minimize this.
This is always a good habit to minimize all of your code so that you can see more of the file and get
more idea of it.
Okay, this is all good.
Now let's go ahead and paste it up here.
So I'm going to add a comment here which will be saying swagger docs related and let's paste this.
So obviously in the first line, our line number six, we are requiring a swagger UI which is being
coming up from the Swagger UI Express which we have just installed now.
Also, it is asking us to bring in a documentation or a document file, which is a swagger or JSON,
and it also says app dot use.
Now this is something where we are going to have a lot more discussion about use as a middleware.
What is a middleware?
What does where we can use it.
We're going to all understand this, but a whole lot of packages actually use this one and it is quite
common thing.
Sometimes you don't think too much and just throw it up here in the code app dot use as soon as you
install some packages.
But don't you worry we will have a detailed discussion on this one.
The one route that we are defining is slash API dash docs and then we are having swagger UI serve and
swagger UI setup and it pass on this document here.
Now this is all OC and also I would like to bring up a change here.
So in the package start, Jason, we have already deployed this one, so we won't be doing any changes
on this one.
So we'll be simply going ahead and we'll be saying Node mod OC.
So this is all good and let's go ahead and run an NPM start on this one.
So and PMS.
Art.
There we go.
And it says, hey, there is a package, there is a social app, the module not found.
So already this has broken our code.
It simply says swag or JSON.
I couldn't find this file.
This was meant to be happen because we don't have that file.
But the reason why I'm not creating this file is because I want to bring your attention onto something
more than the documentation.
So whether you use express router, which we'll definitely use later on or you use the general, you
have to go through with that.
The bigger question is, do you really want to use a JSON in this case?
Majority of the time, especially in the big corporates, you're going to see that people don't use
or prefer JSON, they rather like to use the YAML file.
Now YAML has almost similar syntax to JSON but a little bit more cleaner.
I do have a crash course on YAML as well in case you want to check out on my youtube channel.
But again, you won't be needing it that much.
Let me scroll it a little bit.
I don't want to use this.
In fact, this is so common of a property that if you scroll it a little bit, they are going to say
that, hey, we know some of you don't really like the JSON file and you might want to load your swagger
YAML file.
I told you it's so much popular.
So that simply says in this case you have to install another package which is YAML.
JS So let's go ahead and install this one and then we can load up our YAML file.
Let's go ahead and do that.
So we're going to go ahead and say not like that.
And PM install yaml.
Yes, it's a really small package again.
Let's go ahead and look into the documentation.
It says now you can bring up the YAML and then you can load the file like this and pass on this into
the swagger document.
Cool.
That's exactly what we want.
And let's go up here and I don't want this JSON file.
Rather, I would like to bring in my YAML file.
So it again says you need to bring in the swagger dot HTML file.
So I definitely need to have at least one file up here.
I will declare it in the root, but in case you change the file path, obviously just change it up here
as well.
No big deal there.
Let's call this one as swagger dot yaml.
And by the way, there is a short form of a EML and you can write a full yaml kind of html same same
stuff.
Okay.
Now let's go ahead and save this one and run again and PM start.
This time this is running, but still it is going to have some issues.
Now, first thing notice here, the route that we want to look for is API Dash Docs.
So we're going to copy this and move up here and let's go on to our local host for 1000 slash API docs.
So this is saying unable to render the definition, but important thing is that application is not crashing.
And also we are seeing this swagger logo, which is of course, modifiable.
They give you options in the CSS.
We won't be doing that, but this is all what we need.
It says you need to indicate what kind of things you are using the version at least open API three or
something.
So go ahead and tell me that how actually this all is going to be working on.
Now let's go ahead and try to write just this open API 3.0 and all of that.
So let's go into Swagger HTML.
And all I'm going to say is this is open API and this is going to host a version 3.0.0.
Save this one.
And if I go back here, nothing happens.
Interesting.
But if I just go ahead and close this server and start the NPM start again, I come back here and hit
a reload.
Now it says, okay, you have defined the specific version but nothing in there.
But can you see a problem here?
Although we have no HTML installed, but as we are making changes in our YAML file, it's not monitoring
that.
So what's the point of having a Node.js when we cannot actually go ahead and do this?
So we are going to solve this problem right here in this video.
So notice here it is watching the extension of JS, MGUS and JSON.
Now we want it to just monitor my entire package and see that I want to keep a track of another extension
which is YAML.
So how we actually do this now by default in the root folder, if you create a new file which simply
says no demand dot JSON, make sure it is JSON Node.js.
Now in here you can write a whole lot of things by default, the specification are already given.
But what I want to do in this case is I simply want to go ahead and say that please monitor these extension
XD for extension and this is a long string list.
So I want to say that please keep an eye on JS file and also keep keep an eye on these dot JSON file
and also keep an eye on this YAML file.
And usually when I am working on to a long project and something like that, I also like to keep a file
on Gsx and you can add more as you go in and I'm going to save this one.
And notice here now once you do this, you actually have to restart it just one last time.
And once I do this, now it is monitoring the JS, the JSON, YAML and gsx all file.
So if I go ahead and change this one that I don't want to use the version three, I want to use the
version two, I go ahead, save this.
It automatically monitors my change.
I just have to reload.
And now it says, Hey, I'm using the swagger 2.0, so you get the idea.
Let's go ahead and change it back because we'll be using the version three specification.
There we go.
Hit the reload and says, all good.
Okay, quite a lot of interesting stuff that we have studied in this section.
In the next video, we're going to see that how we can write the basic APIs using the YAML and the swagger.
Let's catch up in the next video.