Hey, did everyone stay here?
And welcome to the new section of Swagger Writing Documentation for API.
Now, of course, the obvious question that comes usually to mind while seeing that are we writing documentation
so early?
We haven't designed much in the API.
Of course we have a project which is in the production, but we haven't written anything complex and
this is where the new structure of this course comes into the picture.
I did a detailed analysis of how I can teach more and keep it a more engaging is.
I have seen that when we teach APIs and build the complex authentication, which of course we will do
eventually writing models and MongoDB and a whole bunch of other things.
Your brain goes into the complex process of analyzing and working on just the APIs.
On the other hand, moving things into the production and writing documentation is equally important.
And if you put these sections at the very end, a lot of interest is being lost.
So I thought to restructure this entire course and hence we are here.
So in this section we are going to learn that how we can write amazing, awesome API documentation.
API documentation is something which is usually ignored, but if you want to really build pro grade
application that, then you will obviously be writing some of the documentation.
And let's just agree on the fact everybody knows about it, that the application might be absolutely
awesome, groundbreaking, but nobody likes to write the documentation.
I have even seen that in the offices.
Everybody loves to write the APIs and routes and controllers and all sort of things.
And the moment somebody says, okay, this is all done, now, who is going to write the documentation?
I have literally seen people running into the lunch rooms and out of the offices.
This really happens.
But the fact is, let's just we have to move on and we have to write the documentation.
Somebody needs to do this job.
And eventually, usually the person who writes all of this documentation is the fresh journey of the
company or the intern sometimes.
So yes, I know that no one likes it, but let's go ahead and move on with this fact.
Documentation is an essential part of writing the API, and especially if you are writing services which
include something which other people are going to be using something like more developers will be using
developers from React, Angular, maybe are designing a payment gateway system, then having an amazing
documentation as well.
The best thing you can ever have your application might be adopted by developers or not can absolutely
depend on how awesome the documentation is.
And there are so many resources via which you can write the documentation and we are choosing one of
the industry's best and probably dominating in the industry, which is known as swagger.
Yes, there are other specifications and other tools which can help you to write the documentation,
but we're going to be choosing for the swagger.
Now, let me bring you up onto the swagger pretty quick up and running on this.
So we're going to simply say swagger API and this is going to land you up on this, which is Swagger
IO.
Now, swagger is leading into the industry because of a couple of reasons.
There is a Swagger Hub, which is the pricing version, the online one.
It is also available as an open source tool.
That means you can just go ahead and install that and nobody's stopping you to host your own APIs and
its own documentation.
That's why everybody loves it.
Swagger Docker tools or the swagger tools are also pretty amazing.
In case your company has an axis of this, then your life is going to be much, much easier.
Now, one thing that you probably are going to like about the swagger is that in their pricing system,
they offer a really good free plan that I have seen.
So if you go up into the Swagger Hub, you are going to see that they have their pricing models and
they offer a generous free tier as well for one user and it provides you API ed, which is really a
lifesaver and you'll get to know why this is there and you can host all of that and mark all of these
ones here.
We are going to see how the marking of these APIs are also being done in a whole bunch of other things.
So this is what we got up here as a swagger, and this is the tool that we'll be using.
And you can see all sorts of good names up coming up here.
Now, this is all the basics of the swagger, but swagger has some of the recommendation and some of
the specification that we have to follow.
And for that, of course, we have the links.
So you can use the following links to work with that.
The first one is the specification guideline that how you should structure your swagger documentation
or some context inside it.
And the second one is the basic structure.
Let's open both of them, but you'll be mostly using the second link, which is the basic structure.
So this is the specification.
Currently we are in the version 3.0.3 or 3.0.3.
So this is the definitions and all of that that we'll be using.
I do agree that you wouldn't be understanding much in this video that what this is, what this field
and everything is.
But as we are going to write together some of the documentation, then it will become much, much easier
to understand.
So this is all the basics.
As I told you, you will be most of the.
I am be spending time into the second leg, which is the basic structure.
You can just directly go from here.
I'll provide you this entire presentation so that it's save some time.
So this is how it looks like.
This is what we'll be writing, all of that.
And this is going to give you some of the structures on that.
Okay.
So don't you see don't get scared.
This is a lot of copy pasting that's going to happen and we will be doing that together.
So don't you worry on that part.
Okay.
So this is the basic introduction of how swagger works on and what we're going to do in the swagger
part.
That is an important question.
So we're going to be writing API docs for the same app that we created in the last section.
In case you don't have that, I'll attach a documentation for that.
Just run an NPM install on that and you'll have that.
But I highly recommend to go ahead, complete the previous section and come back up here.
Now how we're going to write that we will be using this package, which is Swagger UI Express.
Since we are using Express, we want to use swagger, we want to use the UI component of it.
It makes sense to use swagger.
UI express for that.
I highly recommend to go ahead and please just have a look on this or at least read some of the lines,
whatever you can understand, but don't sweat it out too much.
I'll help you to understand everything, install everything and write your very first swagger docs.
So that's it for this one.
Go ahead, spend some time in reading at least 15 to 20 minutes, then come back into the next video.
Let's go ahead and write some awesome documentation together.