WEBVTT 00:03.790 --> 00:05.240 Hey there, everyone here. 00:05.260 --> 00:06.580 And welcome to another video. 00:06.580 --> 00:10.930 And in this video, we're going to write our very first basic swagger documentation. 00:11.170 --> 00:15.970 So the way how we write the swagger documentation is, of course, we all the time keep open up this 00:15.970 --> 00:17.360 basic structure link. 00:17.380 --> 00:23.230 This helps us to get a lot of documentation as well as some of the prototypes and all of that, because 00:23.230 --> 00:27.460 remembering all of them is really a tough thing and nobody remembers, especially the documentation 00:27.460 --> 00:28.540 and the syntax of it. 00:28.570 --> 00:32.740 Eventually you learn a few things over the time, but nobody remembers all of this. 00:32.740 --> 00:35.200 So we keep this one as open up all the time. 00:35.200 --> 00:38.890 And next come up is how you want to structure your documentation. 00:38.890 --> 00:43.390 Whether you want to keep it into a separate file, you want to write them on the go and every route. 00:43.390 --> 00:46.710 So how you want to do it, that is all it's going to depend on this. 00:46.720 --> 00:49.260 Let me walk you through with both the path and I'll walk you through that. 00:49.270 --> 00:51.040 What we are going to opt in this case. 00:51.040 --> 00:52.870 But again, there is no wrong or right here. 00:52.870 --> 00:54.550 It just is your preference. 00:54.640 --> 00:59.770 Now, obviously, whatever you do, the swagger UI express is one of the thing which you will obviously 00:59.770 --> 01:00.250 install. 01:00.250 --> 01:01.810 So make sure this is one there. 01:01.840 --> 01:07.180 Now, apart from this, you are also going to notice that some people like to use a different package 01:07.180 --> 01:16.630 alongside with Swagger UI Express and that is Swagger Dash JS Docs and this doc so. 01:16.630 --> 01:23.050 DZ Doc now what you can do is you have to decide that whether you are going to write things on the go 01:23.050 --> 01:24.690 or you will write them into a separate file. 01:24.700 --> 01:28.390 Let me bring up the VS code that has opened up our project already. 01:28.390 --> 01:29.410 So this is the one. 01:30.580 --> 01:36.310 So what happens in some of the cases is if you don't prefer to write your documentation in a separate 01:36.310 --> 01:41.830 file, which is usually the recommended way, but in some cases it makes sense to have the documentation 01:41.830 --> 01:42.850 just above this route. 01:42.850 --> 01:47.920 So whenever you are defining these routes, whether into a separate file or disappear, people actually 01:47.920 --> 01:50.040 come up and write the documentation is here. 01:50.050 --> 01:52.870 How we do that, we put up a slash and two instances. 01:52.870 --> 01:58.360 As soon as you do this, the ending will be there and now you can just use these things. 01:58.360 --> 02:00.190 So you can simply say this. 02:00.280 --> 02:02.320 Let me just walk you through without writing that. 02:02.320 --> 02:07.360 So you can go ahead and simply say, add the rate open API, or you can write swagger here as well and 02:07.360 --> 02:09.100 you can then start writing all of this. 02:09.100 --> 02:14.800 Now what this all is, we will definitely discuss this, but the whole idea is you can go ahead and 02:14.800 --> 02:19.240 simply say open API or swagger and you can start writing a documentation in here. 02:19.240 --> 02:24.670 You can define that this route is going to be slash Facebook and all of that and then start writing 02:24.670 --> 02:26.740 the get post and all these requests. 02:26.860 --> 02:32.650 In case you want to do that, then obviously you have to install this package also, which is the swagger. 02:32.660 --> 02:39.550 JS Doc, now we will not be doing this because in this case I want you to take one step further and 02:39.550 --> 02:45.880 I want you to install less packages and write your documentation into a separate dedicated file, which 02:45.880 --> 02:47.770 makes much more sense in longer run. 02:47.860 --> 02:50.860 So we'll be going with just in the Swagger UI Express. 02:50.860 --> 02:52.690 So let's go ahead and install this one. 02:52.690 --> 02:57.550 So we're going to copy this one and we need just this package, at least as of now, we'll be needing 02:57.550 --> 02:58.150 one more. 02:58.150 --> 03:02.410 So let's go ahead and simply go ahead and install the Swagger UI Express. 03:02.410 --> 03:06.970 Let's go ahead and install this again, a very teeny tiny package, but really, really powerful. 03:06.970 --> 03:07.630 Let's see. 03:07.750 --> 03:10.360 Okay, so this has installed swagger UI Express. 03:10.360 --> 03:11.410 We are all happy. 03:11.530 --> 03:12.070 Okay. 03:12.550 --> 03:14.200 Moving on in the documentation. 03:14.200 --> 03:15.550 So we have installed it now. 03:15.550 --> 03:16.870 Obviously we need swagger. 03:16.870 --> 03:19.810 So we're going to go ahead and borrow this line up here. 03:19.810 --> 03:25.270 And these two these three lines, actually, we need all three of them and let's dissect them so that 03:25.270 --> 03:26.710 we can understand them fully. 03:27.010 --> 03:29.350 And I'm going to also go ahead and minimize this. 03:29.350 --> 03:35.380 This is always a good habit to minimize all of your code so that you can see more of the file and get 03:35.380 --> 03:36.400 more idea of it. 03:36.430 --> 03:37.750 Okay, this is all good. 03:37.870 --> 03:40.180 Now let's go ahead and paste it up here. 03:40.180 --> 03:49.750 So I'm going to add a comment here which will be saying swagger docs related and let's paste this. 03:50.080 --> 03:55.990 So obviously in the first line, our line number six, we are requiring a swagger UI which is being 03:55.990 --> 03:59.920 coming up from the Swagger UI Express which we have just installed now. 03:59.920 --> 04:06.010 Also, it is asking us to bring in a documentation or a document file, which is a swagger or JSON, 04:06.070 --> 04:08.680 and it also says app dot use. 04:08.680 --> 04:13.750 Now this is something where we are going to have a lot more discussion about use as a middleware. 04:13.750 --> 04:14.860 What is a middleware? 04:14.890 --> 04:16.780 What does where we can use it. 04:16.780 --> 04:20.980 We're going to all understand this, but a whole lot of packages actually use this one and it is quite 04:20.980 --> 04:21.790 common thing. 04:22.000 --> 04:27.280 Sometimes you don't think too much and just throw it up here in the code app dot use as soon as you 04:27.280 --> 04:28.300 install some packages. 04:28.300 --> 04:31.180 But don't you worry we will have a detailed discussion on this one. 04:31.390 --> 04:37.870 The one route that we are defining is slash API dash docs and then we are having swagger UI serve and 04:37.870 --> 04:40.930 swagger UI setup and it pass on this document here. 04:41.050 --> 04:44.560 Now this is all OC and also I would like to bring up a change here. 04:44.560 --> 04:49.360 So in the package start, Jason, we have already deployed this one, so we won't be doing any changes 04:49.360 --> 04:50.050 on this one. 04:50.050 --> 04:56.290 So we'll be simply going ahead and we'll be saying Node mod OC. 04:56.290 --> 05:00.880 So this is all good and let's go ahead and run an NPM start on this one. 05:00.880 --> 05:01.630 So and PMS. 05:01.770 --> 05:02.230 Art. 05:02.280 --> 05:03.120 There we go. 05:03.240 --> 05:08.200 And it says, hey, there is a package, there is a social app, the module not found. 05:08.220 --> 05:10.110 So already this has broken our code. 05:10.110 --> 05:11.730 It simply says swag or JSON. 05:11.730 --> 05:13.200 I couldn't find this file. 05:13.290 --> 05:16.740 This was meant to be happen because we don't have that file. 05:16.770 --> 05:21.420 But the reason why I'm not creating this file is because I want to bring your attention onto something 05:21.420 --> 05:22.920 more than the documentation. 05:22.920 --> 05:28.050 So whether you use express router, which we'll definitely use later on or you use the general, you 05:28.050 --> 05:29.350 have to go through with that. 05:29.370 --> 05:33.030 The bigger question is, do you really want to use a JSON in this case? 05:33.030 --> 05:37.020 Majority of the time, especially in the big corporates, you're going to see that people don't use 05:37.020 --> 05:40.710 or prefer JSON, they rather like to use the YAML file. 05:40.740 --> 05:45.530 Now YAML has almost similar syntax to JSON but a little bit more cleaner. 05:45.600 --> 05:49.770 I do have a crash course on YAML as well in case you want to check out on my youtube channel. 05:49.770 --> 05:51.840 But again, you won't be needing it that much. 05:52.140 --> 05:53.520 Let me scroll it a little bit. 05:53.520 --> 05:54.600 I don't want to use this. 05:54.600 --> 05:59.760 In fact, this is so common of a property that if you scroll it a little bit, they are going to say 05:59.760 --> 06:06.210 that, hey, we know some of you don't really like the JSON file and you might want to load your swagger 06:06.210 --> 06:07.210 YAML file. 06:07.210 --> 06:09.270 I told you it's so much popular. 06:09.270 --> 06:12.990 So that simply says in this case you have to install another package which is YAML. 06:12.990 --> 06:18.390 JS So let's go ahead and install this one and then we can load up our YAML file. 06:18.390 --> 06:19.800 Let's go ahead and do that. 06:19.800 --> 06:23.250 So we're going to go ahead and say not like that. 06:24.740 --> 06:27.110 And PM install yaml. 06:27.260 --> 06:29.300 Yes, it's a really small package again. 06:29.330 --> 06:31.690 Let's go ahead and look into the documentation. 06:31.700 --> 06:37.550 It says now you can bring up the YAML and then you can load the file like this and pass on this into 06:37.550 --> 06:38.660 the swagger document. 06:38.690 --> 06:39.080 Cool. 06:39.080 --> 06:40.520 That's exactly what we want. 06:40.940 --> 06:44.000 And let's go up here and I don't want this JSON file. 06:44.000 --> 06:46.960 Rather, I would like to bring in my YAML file. 06:46.970 --> 06:50.390 So it again says you need to bring in the swagger dot HTML file. 06:50.390 --> 06:53.450 So I definitely need to have at least one file up here. 06:53.600 --> 06:57.890 I will declare it in the root, but in case you change the file path, obviously just change it up here 06:57.890 --> 06:58.170 as well. 06:58.190 --> 06:59.150 No big deal there. 06:59.330 --> 07:03.830 Let's call this one as swagger dot yaml. 07:03.830 --> 07:09.950 And by the way, there is a short form of a EML and you can write a full yaml kind of html same same 07:09.950 --> 07:10.370 stuff. 07:10.610 --> 07:10.920 Okay. 07:10.940 --> 07:14.900 Now let's go ahead and save this one and run again and PM start. 07:15.860 --> 07:19.560 This time this is running, but still it is going to have some issues. 07:19.580 --> 07:23.690 Now, first thing notice here, the route that we want to look for is API Dash Docs. 07:23.690 --> 07:30.500 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. 07:30.650 --> 07:37.160 So this is saying unable to render the definition, but important thing is that application is not crashing. 07:37.160 --> 07:40.780 And also we are seeing this swagger logo, which is of course, modifiable. 07:40.790 --> 07:42.420 They give you options in the CSS. 07:42.440 --> 07:44.990 We won't be doing that, but this is all what we need. 07:45.020 --> 07:50.570 It says you need to indicate what kind of things you are using the version at least open API three or 07:50.570 --> 07:51.020 something. 07:51.020 --> 07:54.890 So go ahead and tell me that how actually this all is going to be working on. 07:55.160 --> 07:59.570 Now let's go ahead and try to write just this open API 3.0 and all of that. 07:59.570 --> 08:01.940 So let's go into Swagger HTML. 08:02.030 --> 08:08.600 And all I'm going to say is this is open API and this is going to host a version 3.0.0. 08:08.660 --> 08:09.920 Save this one. 08:09.920 --> 08:12.890 And if I go back here, nothing happens. 08:13.490 --> 08:14.270 Interesting. 08:14.270 --> 08:20.120 But if I just go ahead and close this server and start the NPM start again, I come back here and hit 08:20.120 --> 08:20.630 a reload. 08:20.630 --> 08:25.130 Now it says, okay, you have defined the specific version but nothing in there. 08:25.550 --> 08:27.620 But can you see a problem here? 08:27.860 --> 08:33.110 Although we have no HTML installed, but as we are making changes in our YAML file, it's not monitoring 08:33.110 --> 08:33.470 that. 08:33.470 --> 08:38.810 So what's the point of having a Node.js when we cannot actually go ahead and do this? 08:38.810 --> 08:41.510 So we are going to solve this problem right here in this video. 08:41.660 --> 08:47.120 So notice here it is watching the extension of JS, MGUS and JSON. 08:47.120 --> 08:54.350 Now we want it to just monitor my entire package and see that I want to keep a track of another extension 08:54.350 --> 08:55.490 which is YAML. 08:55.490 --> 09:00.890 So how we actually do this now by default in the root folder, if you create a new file which simply 09:00.890 --> 09:07.160 says no demand dot JSON, make sure it is JSON Node.js. 09:07.280 --> 09:12.920 Now in here you can write a whole lot of things by default, the specification are already given. 09:12.920 --> 09:18.800 But what I want to do in this case is I simply want to go ahead and say that please monitor these extension 09:18.830 --> 09:22.010 XD for extension and this is a long string list. 09:22.010 --> 09:30.170 So I want to say that please keep an eye on JS file and also keep keep an eye on these dot JSON file 09:30.170 --> 09:33.380 and also keep an eye on this YAML file. 09:33.380 --> 09:38.990 And usually when I am working on to a long project and something like that, I also like to keep a file 09:38.990 --> 09:44.390 on Gsx and you can add more as you go in and I'm going to save this one. 09:44.390 --> 09:49.190 And notice here now once you do this, you actually have to restart it just one last time. 09:49.190 --> 09:55.790 And once I do this, now it is monitoring the JS, the JSON, YAML and gsx all file. 09:55.820 --> 10:00.320 So if I go ahead and change this one that I don't want to use the version three, I want to use the 10:00.320 --> 10:02.480 version two, I go ahead, save this. 10:02.480 --> 10:04.220 It automatically monitors my change. 10:04.220 --> 10:05.570 I just have to reload. 10:05.570 --> 10:10.550 And now it says, Hey, I'm using the swagger 2.0, so you get the idea. 10:10.760 --> 10:14.930 Let's go ahead and change it back because we'll be using the version three specification. 10:14.930 --> 10:15.530 There we go. 10:15.530 --> 10:17.330 Hit the reload and says, all good. 10:17.540 --> 10:21.320 Okay, quite a lot of interesting stuff that we have studied in this section. 10:21.320 --> 10:27.080 In the next video, we're going to see that how we can write the basic APIs using the YAML and the swagger. 10:27.110 --> 10:28.700 Let's catch up in the next video.