WEBVTT 00:03.790 --> 00:08.650 One thing that I would like to mention here is that writing documentation is not tough. 00:08.650 --> 00:09.970 It just is tedious. 00:10.000 --> 00:11.380 Hey, there, everyone is here. 00:11.380 --> 00:12.580 And welcome to another video. 00:12.580 --> 00:16.390 And in this section, we're trying to learn how we can write the documentation. 00:16.570 --> 00:22.660 A lot of time people just see that people are programmers actually run away from the documentation because 00:22.660 --> 00:23.080 it's tough. 00:23.080 --> 00:23.740 No, it's not. 00:23.740 --> 00:26.680 Programmer never, ever runs away from the tough stuff. 00:26.680 --> 00:29.380 They always don't like the tedious stuff. 00:29.380 --> 00:32.290 And writing the documentation is moreover like a tedious work. 00:32.290 --> 00:35.170 And that's why so many tools and stuff is available. 00:35.170 --> 00:36.640 Still a tedious process. 00:36.760 --> 00:41.800 In this video, we're going to see that how we can further define our verbs, can write routes and parameters 00:41.800 --> 00:48.850 and what is expected in the request when we send this request and what is expected as a response to 00:48.850 --> 00:49.600 all of that. 00:49.600 --> 00:54.100 So for this, if you go up here, you can see that we have all the API structures and all of that. 00:54.100 --> 00:59.380 So path and operation is the one and there is definitely not too much going on, just the basic stuff. 00:59.380 --> 01:00.940 So you can define your parts. 01:00.940 --> 01:05.710 So whatever your parts are like you are paying your users and user ID, you can just go ahead and define 01:05.710 --> 01:10.900 that in each of the path you get those get patched, delete, put all of the kind of verbs that you 01:10.900 --> 01:11.640 can put up. 01:11.650 --> 01:13.750 Now, a couple of things I would like to bring your attention. 01:13.750 --> 01:19.510 You can also do path templating so you can provide the slash user and this curly braces and ID in case 01:19.510 --> 01:25.870 you are expecting some parameter into the URL, you can also go ahead and simply request some in the 01:25.870 --> 01:27.910 request query strings. 01:27.910 --> 01:28.810 So this is the one. 01:28.810 --> 01:31.270 So I told you the question mark role equals role. 01:31.270 --> 01:33.520 So you can just go ahead and define it like this. 01:33.520 --> 01:35.080 So that is also possible. 01:35.080 --> 01:40.240 One good thing that is obviously is necessary for writing the documentation is deprecated. 01:40.240 --> 01:46.090 So in case some of the routes that are no longer available, you still have to mention that because 01:46.090 --> 01:50.170 some old people might be using it or old adopters of your applications. 01:50.170 --> 01:54.460 In that case, you can just go ahead and say that this route was there, but now it's being deprecated. 01:54.460 --> 01:56.800 All you got to do is simply mark deprecated. 01:56.800 --> 01:57.340 True. 01:57.340 --> 02:03.130 So this is all the basics and rest will be easier for you to understand as we go into the documentation 02:03.130 --> 02:03.700 part. 02:03.730 --> 02:04.230 Okay. 02:04.750 --> 02:08.320 So all of your things like components and stuff actually goes up here. 02:08.320 --> 02:09.910 So that is at the very top. 02:10.360 --> 02:16.450 And once you're done with that, then we can go head into this one and then we can simply mention the 02:16.450 --> 02:17.590 paths like this. 02:17.590 --> 02:18.490 And there we go. 02:18.490 --> 02:20.680 Now into the path, how we're going to work with that. 02:20.680 --> 02:22.360 Make sure you keep an eye on the indentation. 02:22.360 --> 02:25.180 This is the biggest devil of writing the docs. 02:25.180 --> 02:28.720 So we're going to go ahead and simply say this is the path of Instagram. 02:28.720 --> 02:31.900 Remember the slash API, slash V1 is already there. 02:31.900 --> 02:35.860 So I need to just append an Instagram here, which is Instagram. 02:36.010 --> 02:36.490 Okay. 02:36.580 --> 02:39.190 Now what happens in this Instagram AR route? 02:39.190 --> 02:45.280 Now, if I put up a just this one, an indentation, I can write my get put post all of these ones. 02:45.280 --> 02:48.070 Let's start with the get one because this is a simple get route. 02:48.070 --> 02:49.300 That's what we are doing. 02:49.300 --> 02:51.550 Now, let me move this a little bit up. 02:51.550 --> 02:52.240 There we go. 02:52.330 --> 02:54.280 So what happens into this get root? 02:54.280 --> 02:58.180 First thing is we write a simple summary that what happens at this root? 02:58.180 --> 03:06.370 So we're going to simply say it returns username followers and followers. 03:06.370 --> 03:09.100 And yes, you have to write that there is no escape from this one. 03:09.370 --> 03:16.330 Now after this, you write simply responses and you can have as many responses as you wish to have or 03:16.330 --> 03:19.780 whatever is defined into, well, writing the code for this one. 03:19.780 --> 03:25.300 So in this case we are going to simply say we have a response of 200, which is usually the status code. 03:25.300 --> 03:27.910 So you can use a hashtag which is a status code. 03:27.910 --> 03:33.340 And by the way, this is status code and hash is a comment pretty obvious to spot on there and then 03:33.340 --> 03:38.740 make sure you indent in there because after the status code, this comes up here so this one can again 03:38.740 --> 03:48.520 have a description and this can say that this is a success and we are going to return an object or simply 03:48.520 --> 03:52.480 say is returns an object and I forgot a colon here. 03:52.480 --> 03:53.470 That's why it's yelling. 03:53.470 --> 03:55.990 So again, extension really helps out a lot. 03:56.860 --> 03:57.400 Okay. 03:57.400 --> 04:03.310 Now, once this is being done, this is just the description, but this is okay, but we can do a little 04:03.310 --> 04:03.640 bit more. 04:03.640 --> 04:04.420 Let's first see that. 04:04.420 --> 04:07.000 What kind of changes does it make? 04:07.000 --> 04:13.030 As of now, if I go back up here, hit a reload, and now we can see that we have a get request, which 04:13.030 --> 04:16.780 is a slash Instagram, it returns a username, followers and followers. 04:16.780 --> 04:17.920 I can click on this. 04:17.920 --> 04:22.000 I can simply say try out and execute and just executes. 04:22.000 --> 04:27.370 It does nothing because we haven't mentioned that what happens, what kind of content it returns and 04:27.370 --> 04:28.240 all a bunch of things. 04:28.240 --> 04:30.310 So let's go ahead and try out that part. 04:30.610 --> 04:35.320 So we're going to simply say this is description, responses and responses. 04:35.320 --> 04:37.900 Yep, responses. 04:38.170 --> 04:41.740 Okay, should be good now and at least we should be able to see responses now. 04:41.740 --> 04:43.480 Let's go ahead and try to hit a reload. 04:43.900 --> 04:44.680 And there we go. 04:44.680 --> 04:47.500 It returns an object, but definitely it doesn't do much. 04:47.650 --> 04:49.300 It just gets you all of this. 04:49.660 --> 04:52.990 Now notice here it says response body is username follows. 04:52.990 --> 04:54.580 And of course we are bringing in data as well. 04:54.580 --> 04:58.870 So this is all the headers that you are taking along with you and all of that. 04:58.870 --> 05:00.520 Now let me show you one more thing. 05:00.520 --> 05:01.690 If I just go ahead and say. 05:01.790 --> 05:02.480 Authorize. 05:02.480 --> 05:07.360 And I simply say test and I authorize this and I close this one. 05:07.370 --> 05:09.770 Now let's try to execute it one more time. 05:09.770 --> 05:13.700 And I hope you can see that it is not taking any of this as of now. 05:13.730 --> 05:18.800 Now, you need to specifically mention that for that, if you are bringing it up, that again, this 05:18.800 --> 05:22.010 is a whole lot of another dimension that we can bring in. 05:22.010 --> 05:28.280 So again, reading is always a good friend, but this is all okay, I want to make it a little bit more 05:28.310 --> 05:30.290 better, so let's go ahead and do that. 05:30.290 --> 05:32.090 We can add more of the stuff here. 05:32.480 --> 05:36.200 So this is my description, but I want a little bit more up here. 05:36.200 --> 05:39.320 So I'm going to say that I am having a content. 05:39.680 --> 05:41.090 So what is your content type? 05:41.090 --> 05:42.230 It should be clear as well. 05:42.230 --> 05:46.220 So this one is going to be application slash JSON. 05:47.000 --> 05:49.790 Now we can further define our schema to that. 05:49.790 --> 05:56.240 What kind of schema is being followed by the response so that user can actually get more friendlier 05:56.240 --> 06:00.440 that what kind of result I'm having, whether I have to look through it or I have to dig up into the 06:00.440 --> 06:02.150 object however you like to go. 06:02.150 --> 06:04.460 So here you can define the type of schema. 06:04.460 --> 06:06.260 In this case it can be an array. 06:06.260 --> 06:09.110 I am having an object, so I'm going to just write an object. 06:09.110 --> 06:11.900 And as soon as you write object, obviously you have to write. 06:11.900 --> 06:17.720 Property is not compulsory, but it is good that if you write properties, what properties define is 06:17.720 --> 06:20.960 properties simply mentioned that how your schema looks like. 06:20.960 --> 06:24.560 So in our schema we have a user name that comes up. 06:24.560 --> 06:28.910 Now the type of this user name is of string. 06:28.910 --> 06:31.310 There can be numbers and other stuff as well. 06:31.400 --> 06:37.460 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 06:37.460 --> 06:41.690 a followers, we also get a follows. 06:41.840 --> 06:43.160 We also have a date. 06:43.160 --> 06:48.590 But I just want to show you that how it looks like because again, nobody likes the documentation writing, 06:48.590 --> 06:49.370 including me. 06:49.370 --> 06:52.160 So let's go ahead and hit a reload up here. 06:52.400 --> 06:59.630 And now if I go up here, I can see that there is no parameters required, but the content type is application 06:59.630 --> 07:05.810 JSON and then we can see at the bottom again, just let me shrink this a little bit up here so that 07:05.810 --> 07:07.010 you can see it nicely. 07:07.220 --> 07:11.900 So we can see that we have a user name string follows and all of that. 07:11.900 --> 07:14.660 Now we can actually go ahead and try it out, execute that. 07:14.660 --> 07:19.220 This will give us a response that this is the response you are receiving in the body and this is the 07:19.220 --> 07:20.990 response you are receiving in the headers. 07:21.290 --> 07:25.160 Remember I told you that we can actually authorize it when we are authorizing. 07:25.160 --> 07:30.380 We need to clearly mention that at the time of making a request we are taking these parameters with 07:30.380 --> 07:30.710 us. 07:30.710 --> 07:32.390 So we need to understand that as well. 07:32.390 --> 07:39.290 But before we do that, I want to show you one more stuff that I can just go ahead and take this from 07:39.290 --> 07:42.080 the get and select all of this. 07:42.080 --> 07:48.440 And I can make a copy of this and I can say, Hey, this is going to be my post request and you can 07:48.440 --> 07:51.140 make get put post however you like to go. 07:51.230 --> 07:56.570 Obviously we don't have any post route that is supporting anything, but if you do this, you get the 07:56.570 --> 07:58.160 idea that how easy it is. 07:58.310 --> 08:02.750 Once you have defined one structure, it is really easy to define copy paste and this stuff. 08:03.110 --> 08:06.950 This will definitely make a post request, but we don't have nothing out of now. 08:07.100 --> 08:13.010 The one thing which is going to teach us a little bit more about taking things with us, which is parameters, 08:13.010 --> 08:19.550 is the route that we defined for this a special occasion, which is if I go to the index, we do have 08:19.550 --> 08:25.340 a route which takes this token up here, so we need to define UI or the documentation for that. 08:25.340 --> 08:32.540 Also, let's go ahead and actually just grab this post and we are going to go ahead and make a copy 08:32.540 --> 08:32.780 of this. 08:32.780 --> 08:39.620 By the way, I'm using shift option and the down arrow key, which is in the Windows case shift and 08:39.890 --> 08:43.310 all key and the down arrow, these are just VZ code shortcuts. 08:44.420 --> 08:47.450 So this time this is definitely a post request. 08:47.450 --> 08:51.230 But what I want to do apart from this post request is the route is getting changed. 08:51.230 --> 08:56.600 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 08:56.660 --> 08:58.880 since we are taking some things in the URL. 08:58.880 --> 09:01.280 So I'm going to go ahead and say this is a token. 09:01.280 --> 09:06.920 Now, again, once this is all there, you need to go back up here and there we go. 09:06.920 --> 09:10.580 Now this indentation is bad, so I'm going to just select this one up here. 09:10.580 --> 09:16.160 And till all the all the way up here, hold down your control key and use the square brackets and it 09:16.160 --> 09:17.300 will just move the things. 09:17.300 --> 09:21.290 This is much better of a syntax when you are having all these things. 09:21.290 --> 09:25.850 So this one says, hey, you are having a get root, you forgot a colon. 09:25.850 --> 09:26.360 There we go. 09:26.370 --> 09:27.470 Should be all happy now. 09:27.650 --> 09:29.990 Now, at least now we should be able to see this. 09:30.530 --> 09:33.740 Let's see if hope the documentation doesn't got broken. 09:33.980 --> 09:39.860 Let's say to reload and we see that we have a get but we haven't defined the root. 09:39.860 --> 09:40.730 Seems like. 09:41.960 --> 09:42.440 Okay. 09:42.440 --> 09:43.880 So this is a post. 09:44.780 --> 09:45.830 Let me just shrink this. 09:45.830 --> 09:50.120 This is a get this is a post and this indentation is bad. 09:50.120 --> 09:52.310 So we're going to just select all of this. 09:52.520 --> 09:55.700 And again, as I told you, there is no escape from this. 09:56.060 --> 10:00.020 And now this should be all happy because these are all on the same level. 10:00.020 --> 10:03.890 So save that and let's see if the documentation is happy now. 10:03.890 --> 10:04.310 Yep. 10:04.310 --> 10:04.940 There we go. 10:05.150 --> 10:05.540 Okay. 10:05.570 --> 10:07.850 So let's go ahead and modify this one. 10:08.060 --> 10:10.550 This is first and foremost is not a post. 10:10.550 --> 10:12.680 This is a get root that we are working on. 10:12.680 --> 10:25.670 Summary is good enough or let's just say summary is going to be returns, whatever is there in parameter. 10:27.320 --> 10:29.240 So how we're going to do this? 10:29.420 --> 10:33.890 Previously we were defining only the response, but now after this, we have to define that what kind 10:33.890 --> 10:35.420 of parameters we are taking. 10:35.420 --> 10:39.500 So as soon as you write the parameters, then you can just go ahead and define it. 10:39.530 --> 10:41.810 The first thing I'm going to say is the name. 10:41.810 --> 10:44.480 The name of the parameter by default is token. 10:44.780 --> 10:47.510 And I can also provide a default value to this one. 10:47.510 --> 10:49.970 So I'm going to say default. 10:50.240 --> 10:55.220 And the default value is, let's just say five, any number, name, whatever you want to pass on as 10:55.220 --> 10:56.000 a default. 10:56.360 --> 10:58.190 I'll show you that what this is in a minute. 10:58.310 --> 11:01.760 So inside that we can say that, where do we expect it? 11:01.760 --> 11:04.040 In the path, in the query parameter. 11:04.040 --> 11:06.020 Again, nobody remembers that. 11:06.050 --> 11:12.080 Almost nobody that I know of, they always go up here and they always look for where do we want to pass 11:12.080 --> 11:12.530 it up? 11:12.770 --> 11:16.340 So all these information is given up in the path templating. 11:16.760 --> 11:18.500 Notice here it says slash ping. 11:18.500 --> 11:23.450 So all these information notice here, this says path because you want to bring it in the path if you 11:23.450 --> 11:27.230 want it into the cookies or queries, this is all you have to write. 11:27.230 --> 11:31.490 And again, there is a whole section on if you want to take something from the cookies and all of that. 11:31.490 --> 11:33.590 So there is everything mentioned. 11:33.890 --> 11:40.640 Okay, so I want to take this from the path you can optionally define the schema of everything. 11:40.640 --> 11:44.960 Whatever you are taking in, whatever you are sending back, it's up to you whether you want to define 11:44.960 --> 11:45.680 it or not. 11:45.680 --> 11:47.210 In my case, I want to. 11:47.210 --> 11:49.610 So this is of type string. 11:50.150 --> 11:52.610 Okay, now what happens after this one? 11:53.210 --> 11:57.530 Again, definitely our schema is different this time we are definitely accepting application. 11:57.530 --> 12:00.410 JSON schema is not object. 12:00.620 --> 12:01.970 Yeah, schema is object. 12:01.970 --> 12:04.490 But we are not having this many of properties. 12:04.870 --> 12:11.570 We are just returning whatever comes back and we are calling this as params should be all happy. 12:11.570 --> 12:14.480 Now let's see if our documentation is also happy. 12:14.480 --> 12:16.250 Let's go ahead and reload this one. 12:16.250 --> 12:18.950 And now we can see that we have a get request on the token. 12:18.950 --> 12:24.590 Let's see how it looks like and anybody can come up and say that the default value is five, it returns 12:24.590 --> 12:29.330 whatever is there in the parameters and you need to pass it on as in path. 12:29.330 --> 12:34.610 So whatever you write here is going to go into the path application, JSON, the whatever is going to 12:34.610 --> 12:40.190 come back is in the format of an object and params is the key and the string is going to be the value. 12:40.220 --> 12:41.930 Let's go ahead and hit a try out. 12:41.960 --> 12:47.510 Now instead of the token, I'm going to say hit hash and I'm going to go ahead and execute this. 12:47.510 --> 12:50.960 And we see that the params comes back. 12:50.960 --> 12:54.950 This is the URL that it got hit and the rest of the things are pretty okay. 12:54.950 --> 13:00.920 Now importantly, if I hit a reload again, the notice here when I say try out it, all those say is 13:00.920 --> 13:01.280 five. 13:01.280 --> 13:04.790 But when I execute this, this actually gives me five appear. 13:04.790 --> 13:08.240 So this is this is what exactly literally this default means. 13:08.240 --> 13:14.390 So if nobody ends, enters any value, you just pass on this default, you can just pass on a default 13:14.540 --> 13:14.930 token. 13:14.930 --> 13:16.370 This name is for your reference. 13:16.370 --> 13:18.440 It doesn't do much, but you get the idea. 13:18.830 --> 13:20.690 Okay, so quite a lot. 13:20.690 --> 13:25.580 But really interesting part that how you write the documentation and yes, you have to do it for every 13:25.580 --> 13:26.870 single route that is there. 13:26.870 --> 13:32.390 You have to define the schema of what is expected in the parameters and in what format, maybe in the 13:32.390 --> 13:37.790 tokens headers session or just as a parameter or request query. 13:37.790 --> 13:39.020 And then in the response. 13:39.020 --> 13:43.700 Also you have to define the schema that how the schema will return back, whether it's an object, user, 13:43.700 --> 13:45.350 product, whatever that is. 13:45.560 --> 13:46.850 So that's it. 13:46.850 --> 13:48.980 That is your intro with the documentation. 13:48.980 --> 13:50.840 Let's go ahead and catch up in the next video.