One thing that I would like to mention here is that writing documentation is not tough.
It just is tedious.
Hey, there, everyone is here.
And welcome to another video.
And in this section, we're trying to learn how we can write the documentation.
A lot of time people just see that people are programmers actually run away from the documentation because
it's tough.
No, it's not.
Programmer never, ever runs away from the tough stuff.
They always don't like the tedious stuff.
And writing the documentation is moreover like a tedious work.
And that's why so many tools and stuff is available.
Still a tedious process.
In this video, we're going to see that how we can further define our verbs, can write routes and parameters
and what is expected in the request when we send this request and what is expected as a response to
all of that.
So for this, if you go up here, you can see that we have all the API structures and all of that.
So path and operation is the one and there is definitely not too much going on, just the basic stuff.
So you can define your parts.
So whatever your parts are like you are paying your users and user ID, you can just go ahead and define
that in each of the path you get those get patched, delete, put all of the kind of verbs that you
can put up.
Now, a couple of things I would like to bring your attention.
You can also do path templating so you can provide the slash user and this curly braces and ID in case
you are expecting some parameter into the URL, you can also go ahead and simply request some in the
request query strings.
So this is the one.
So I told you the question mark role equals role.
So you can just go ahead and define it like this.
So that is also possible.
One good thing that is obviously is necessary for writing the documentation is deprecated.
So in case some of the routes that are no longer available, you still have to mention that because
some old people might be using it or old adopters of your applications.
In that case, you can just go ahead and say that this route was there, but now it's being deprecated.
All you got to do is simply mark deprecated.
True.
So this is all the basics and rest will be easier for you to understand as we go into the documentation
part.
Okay.
So all of your things like components and stuff actually goes up here.
So that is at the very top.
And once you're done with that, then we can go head into this one and then we can simply mention the
paths like this.
And there we go.
Now into the path, how we're going to work with that.
Make sure you keep an eye on the indentation.
This is the biggest devil of writing the docs.
So we're going to go ahead and simply say this is the path of Instagram.
Remember the slash API, slash V1 is already there.
So I need to just append an Instagram here, which is Instagram.
Okay.
Now what happens in this Instagram AR route?
Now, if I put up a just this one, an indentation, I can write my get put post all of these ones.
Let's start with the get one because this is a simple get route.
That's what we are doing.
Now, let me move this a little bit up.
There we go.
So what happens into this get root?
First thing is we write a simple summary that what happens at this root?
So we're going to simply say it returns username followers and followers.
And yes, you have to write that there is no escape from this one.
Now after this, you write simply responses and you can have as many responses as you wish to have or
whatever is defined into, well, writing the code for this one.
So in this case we are going to simply say we have a response of 200, which is usually the status code.
So you can use a hashtag which is a status code.
And by the way, this is status code and hash is a comment pretty obvious to spot on there and then
make sure you indent in there because after the status code, this comes up here so this one can again
have a description and this can say that this is a success and we are going to return an object or simply
say is returns an object and I forgot a colon here.
That's why it's yelling.
So again, extension really helps out a lot.
Okay.
Now, once this is being done, this is just the description, but this is okay, but we can do a little
bit more.
Let's first see that.
What kind of changes does it make?
As of now, if I go back up here, hit a reload, and now we can see that we have a get request, which
is a slash Instagram, it returns a username, followers and followers.
I can click on this.
I can simply say try out and execute and just executes.
It does nothing because we haven't mentioned that what happens, what kind of content it returns and
all a bunch of things.
So let's go ahead and try out that part.
So we're going to simply say this is description, responses and responses.
Yep, responses.
Okay, should be good now and at least we should be able to see responses now.
Let's go ahead and try to hit a reload.
And there we go.
It returns an object, but definitely it doesn't do much.
It just gets you all of this.
Now notice here it says response body is username follows.
And of course we are bringing in data as well.
So this is all the headers that you are taking along with you and all of that.
Now let me show you one more thing.
If I just go ahead and say.
Authorize.
And I simply say test and I authorize this and I close this one.
Now let's try to execute it one more time.
And I hope you can see that it is not taking any of this as of now.
Now, you need to specifically mention that for that, if you are bringing it up, that again, this
is a whole lot of another dimension that we can bring in.
So again, reading is always a good friend, but this is all okay, I want to make it a little bit more
better, so let's go ahead and do that.
We can add more of the stuff here.
So this is my description, but I want a little bit more up here.
So I'm going to say that I am having a content.
So what is your content type?
It should be clear as well.
So this one is going to be application slash JSON.
Now we can further define our schema to that.
What kind of schema is being followed by the response so that user can actually get more friendlier
that what kind of result I'm having, whether I have to look through it or I have to dig up into the
object however you like to go.
So here you can define the type of schema.
In this case it can be an array.
I am having an object, so I'm going to just write an object.
And as soon as you write object, obviously you have to write.
Property is not compulsory, but it is good that if you write properties, what properties define is
properties simply mentioned that how your schema looks like.
So in our schema we have a user name that comes up.
Now the type of this user name is of string.
There can be numbers and other stuff as well.
So we're going to go ahead and make a copy of this two times and we're going to simply say we also get
a followers, we also get a follows.
We also have a date.
But I just want to show you that how it looks like because again, nobody likes the documentation writing,
including me.
So let's go ahead and hit a reload up here.
And now if I go up here, I can see that there is no parameters required, but the content type is application
JSON and then we can see at the bottom again, just let me shrink this a little bit up here so that
you can see it nicely.
So we can see that we have a user name string follows and all of that.
Now we can actually go ahead and try it out, execute that.
This will give us a response that this is the response you are receiving in the body and this is the
response you are receiving in the headers.
Remember I told you that we can actually authorize it when we are authorizing.
We need to clearly mention that at the time of making a request we are taking these parameters with
us.
So we need to understand that as well.
But before we do that, I want to show you one more stuff that I can just go ahead and take this from
the get and select all of this.
And I can make a copy of this and I can say, Hey, this is going to be my post request and you can
make get put post however you like to go.
Obviously we don't have any post route that is supporting anything, but if you do this, you get the
idea that how easy it is.
Once you have defined one structure, it is really easy to define copy paste and this stuff.
This will definitely make a post request, but we don't have nothing out of now.
The one thing which is going to teach us a little bit more about taking things with us, which is parameters,
is the route that we defined for this a special occasion, which is if I go to the index, we do have
a route which takes this token up here, so we need to define UI or the documentation for that.
Also, let's go ahead and actually just grab this post and we are going to go ahead and make a copy
of this.
By the way, I'm using shift option and the down arrow key, which is in the Windows case shift and
all key and the down arrow, these are just VZ code shortcuts.
So this time this is definitely a post request.
But what I want to do apart from this post request is the route is getting changed.
So I'm going to hit enter up here and I'll move up here and I'll say this time I'm going for a slash
since we are taking some things in the URL.
So I'm going to go ahead and say this is a token.
Now, again, once this is all there, you need to go back up here and there we go.
Now this indentation is bad, so I'm going to just select this one up here.
And till all the all the way up here, hold down your control key and use the square brackets and it
will just move the things.
This is much better of a syntax when you are having all these things.
So this one says, hey, you are having a get root, you forgot a colon.
There we go.
Should be all happy now.
Now, at least now we should be able to see this.
Let's see if hope the documentation doesn't got broken.
Let's say to reload and we see that we have a get but we haven't defined the root.
Seems like.
Okay.
So this is a post.
Let me just shrink this.
This is a get this is a post and this indentation is bad.
So we're going to just select all of this.
And again, as I told you, there is no escape from this.
And now this should be all happy because these are all on the same level.
So save that and let's see if the documentation is happy now.
Yep.
There we go.
Okay.
So let's go ahead and modify this one.
This is first and foremost is not a post.
This is a get root that we are working on.
Summary is good enough or let's just say summary is going to be returns, whatever is there in parameter.
So how we're going to do this?
Previously we were defining only the response, but now after this, we have to define that what kind
of parameters we are taking.
So as soon as you write the parameters, then you can just go ahead and define it.
The first thing I'm going to say is the name.
The name of the parameter by default is token.
And I can also provide a default value to this one.
So I'm going to say default.
And the default value is, let's just say five, any number, name, whatever you want to pass on as
a default.
I'll show you that what this is in a minute.
So inside that we can say that, where do we expect it?
In the path, in the query parameter.
Again, nobody remembers that.
Almost nobody that I know of, they always go up here and they always look for where do we want to pass
it up?
So all these information is given up in the path templating.
Notice here it says slash ping.
So all these information notice here, this says path because you want to bring it in the path if you
want it into the cookies or queries, this is all you have to write.
And again, there is a whole section on if you want to take something from the cookies and all of that.
So there is everything mentioned.
Okay, so I want to take this from the path you can optionally define the schema of everything.
Whatever you are taking in, whatever you are sending back, it's up to you whether you want to define
it or not.
In my case, I want to.
So this is of type string.
Okay, now what happens after this one?
Again, definitely our schema is different this time we are definitely accepting application.
JSON schema is not object.
Yeah, schema is object.
But we are not having this many of properties.
We are just returning whatever comes back and we are calling this as params should be all happy.
Now let's see if our documentation is also happy.
Let's go ahead and reload this one.
And now we can see that we have a get request on the token.
Let's see how it looks like and anybody can come up and say that the default value is five, it returns
whatever is there in the parameters and you need to pass it on as in path.
So whatever you write here is going to go into the path application, JSON, the whatever is going to
come back is in the format of an object and params is the key and the string is going to be the value.
Let's go ahead and hit a try out.
Now instead of the token, I'm going to say hit hash and I'm going to go ahead and execute this.
And we see that the params comes back.
This is the URL that it got hit and the rest of the things are pretty okay.
Now importantly, if I hit a reload again, the notice here when I say try out it, all those say is
five.
But when I execute this, this actually gives me five appear.
So this is this is what exactly literally this default means.
So if nobody ends, enters any value, you just pass on this default, you can just pass on a default
token.
This name is for your reference.
It doesn't do much, but you get the idea.
Okay, so quite a lot.
But really interesting part that how you write the documentation and yes, you have to do it for every
single route that is there.
You have to define the schema of what is expected in the parameters and in what format, maybe in the
tokens headers session or just as a parameter or request query.
And then in the response.
Also you have to define the schema that how the schema will return back, whether it's an object, user,
product, whatever that is.
So that's it.
That is your intro with the documentation.
Let's go ahead and catch up in the next video.