WEBVTT 00:03.820 --> 00:05.350 Hey, did everyone stay here? 00:05.350 --> 00:10.420 And welcome to the new section of Swagger Writing Documentation for API. 00:10.720 --> 00:16.270 Now, of course, the obvious question that comes usually to mind while seeing that are we writing documentation 00:16.270 --> 00:17.230 so early? 00:17.230 --> 00:19.270 We haven't designed much in the API. 00:19.300 --> 00:23.830 Of course we have a project which is in the production, but we haven't written anything complex and 00:23.830 --> 00:26.830 this is where the new structure of this course comes into the picture. 00:26.860 --> 00:32.530 I did a detailed analysis of how I can teach more and keep it a more engaging is. 00:32.530 --> 00:37.390 I have seen that when we teach APIs and build the complex authentication, which of course we will do 00:37.390 --> 00:41.980 eventually writing models and MongoDB and a whole bunch of other things. 00:41.980 --> 00:47.680 Your brain goes into the complex process of analyzing and working on just the APIs. 00:47.830 --> 00:52.810 On the other hand, moving things into the production and writing documentation is equally important. 00:52.810 --> 00:56.810 And if you put these sections at the very end, a lot of interest is being lost. 00:56.830 --> 01:00.510 So I thought to restructure this entire course and hence we are here. 01:00.550 --> 01:06.580 So in this section we are going to learn that how we can write amazing, awesome API documentation. 01:06.730 --> 01:11.890 API documentation is something which is usually ignored, but if you want to really build pro grade 01:11.890 --> 01:16.660 application that, then you will obviously be writing some of the documentation. 01:16.720 --> 01:22.600 And let's just agree on the fact everybody knows about it, that the application might be absolutely 01:22.600 --> 01:27.240 awesome, groundbreaking, but nobody likes to write the documentation. 01:27.250 --> 01:29.470 I have even seen that in the offices. 01:29.470 --> 01:34.240 Everybody loves to write the APIs and routes and controllers and all sort of things. 01:34.240 --> 01:38.460 And the moment somebody says, okay, this is all done, now, who is going to write the documentation? 01:38.470 --> 01:43.030 I have literally seen people running into the lunch rooms and out of the offices. 01:43.030 --> 01:44.350 This really happens. 01:44.440 --> 01:49.060 But the fact is, let's just we have to move on and we have to write the documentation. 01:49.060 --> 01:51.160 Somebody needs to do this job. 01:51.160 --> 01:56.920 And eventually, usually the person who writes all of this documentation is the fresh journey of the 01:56.920 --> 01:59.200 company or the intern sometimes. 01:59.560 --> 02:04.930 So yes, I know that no one likes it, but let's go ahead and move on with this fact. 02:05.080 --> 02:10.000 Documentation is an essential part of writing the API, and especially if you are writing services which 02:10.000 --> 02:15.280 include something which other people are going to be using something like more developers will be using 02:15.280 --> 02:20.830 developers from React, Angular, maybe are designing a payment gateway system, then having an amazing 02:20.830 --> 02:21.880 documentation as well. 02:21.880 --> 02:29.170 The best thing you can ever have your application might be adopted by developers or not can absolutely 02:29.170 --> 02:31.900 depend on how awesome the documentation is. 02:31.900 --> 02:37.420 And there are so many resources via which you can write the documentation and we are choosing one of 02:37.420 --> 02:42.600 the industry's best and probably dominating in the industry, which is known as swagger. 02:42.610 --> 02:47.590 Yes, there are other specifications and other tools which can help you to write the documentation, 02:47.590 --> 02:49.810 but we're going to be choosing for the swagger. 02:49.840 --> 02:53.620 Now, let me bring you up onto the swagger pretty quick up and running on this. 02:53.620 --> 03:01.390 So we're going to simply say swagger API and this is going to land you up on this, which is Swagger 03:01.630 --> 03:02.170 IO. 03:02.200 --> 03:06.640 Now, swagger is leading into the industry because of a couple of reasons. 03:06.640 --> 03:10.660 There is a Swagger Hub, which is the pricing version, the online one. 03:10.660 --> 03:13.780 It is also available as an open source tool. 03:13.780 --> 03:19.720 That means you can just go ahead and install that and nobody's stopping you to host your own APIs and 03:19.720 --> 03:20.890 its own documentation. 03:20.890 --> 03:22.240 That's why everybody loves it. 03:22.270 --> 03:27.100 Swagger Docker tools or the swagger tools are also pretty amazing. 03:27.100 --> 03:32.170 In case your company has an axis of this, then your life is going to be much, much easier. 03:32.200 --> 03:38.740 Now, one thing that you probably are going to like about the swagger is that in their pricing system, 03:38.740 --> 03:41.350 they offer a really good free plan that I have seen. 03:41.350 --> 03:46.600 So if you go up into the Swagger Hub, you are going to see that they have their pricing models and 03:46.600 --> 03:52.540 they offer a generous free tier as well for one user and it provides you API ed, which is really a 03:52.540 --> 03:57.760 lifesaver and you'll get to know why this is there and you can host all of that and mark all of these 03:57.760 --> 03:58.210 ones here. 03:58.210 --> 04:03.100 We are going to see how the marking of these APIs are also being done in a whole bunch of other things. 04:03.100 --> 04:07.900 So this is what we got up here as a swagger, and this is the tool that we'll be using. 04:07.900 --> 04:10.600 And you can see all sorts of good names up coming up here. 04:10.840 --> 04:16.900 Now, this is all the basics of the swagger, but swagger has some of the recommendation and some of 04:16.900 --> 04:18.730 the specification that we have to follow. 04:18.730 --> 04:21.070 And for that, of course, we have the links. 04:21.070 --> 04:23.590 So you can use the following links to work with that. 04:23.590 --> 04:29.560 The first one is the specification guideline that how you should structure your swagger documentation 04:29.560 --> 04:31.180 or some context inside it. 04:31.180 --> 04:33.100 And the second one is the basic structure. 04:33.130 --> 04:37.990 Let's open both of them, but you'll be mostly using the second link, which is the basic structure. 04:38.140 --> 04:39.700 So this is the specification. 04:39.700 --> 04:44.620 Currently we are in the version 3.0.3 or 3.0.3. 04:44.620 --> 04:48.010 So this is the definitions and all of that that we'll be using. 04:48.280 --> 04:52.780 I do agree that you wouldn't be understanding much in this video that what this is, what this field 04:52.780 --> 04:53.560 and everything is. 04:53.560 --> 04:57.910 But as we are going to write together some of the documentation, then it will become much, much easier 04:57.910 --> 04:58.480 to understand. 04:58.480 --> 04:59.830 So this is all the basics. 04:59.860 --> 05:01.780 As I told you, you will be most of the. 05:01.940 --> 05:05.000 I am be spending time into the second leg, which is the basic structure. 05:05.000 --> 05:06.890 You can just directly go from here. 05:06.920 --> 05:11.210 I'll provide you this entire presentation so that it's save some time. 05:11.300 --> 05:12.760 So this is how it looks like. 05:12.770 --> 05:15.170 This is what we'll be writing, all of that. 05:15.170 --> 05:18.110 And this is going to give you some of the structures on that. 05:18.330 --> 05:18.600 Okay. 05:18.650 --> 05:20.560 So don't you see don't get scared. 05:20.570 --> 05:24.140 This is a lot of copy pasting that's going to happen and we will be doing that together. 05:24.140 --> 05:25.580 So don't you worry on that part. 05:25.950 --> 05:26.270 Okay. 05:26.270 --> 05:31.040 So this is the basic introduction of how swagger works on and what we're going to do in the swagger 05:31.040 --> 05:31.300 part. 05:31.310 --> 05:32.900 That is an important question. 05:32.900 --> 05:37.520 So we're going to be writing API docs for the same app that we created in the last section. 05:37.520 --> 05:40.460 In case you don't have that, I'll attach a documentation for that. 05:40.460 --> 05:43.310 Just run an NPM install on that and you'll have that. 05:43.400 --> 05:47.570 But I highly recommend to go ahead, complete the previous section and come back up here. 05:47.690 --> 05:52.790 Now how we're going to write that we will be using this package, which is Swagger UI Express. 05:52.790 --> 05:57.560 Since we are using Express, we want to use swagger, we want to use the UI component of it. 05:57.590 --> 05:59.180 It makes sense to use swagger. 05:59.180 --> 06:00.650 UI express for that. 06:00.680 --> 06:07.370 I highly recommend to go ahead and please just have a look on this or at least read some of the lines, 06:07.370 --> 06:09.950 whatever you can understand, but don't sweat it out too much. 06:09.950 --> 06:14.990 I'll help you to understand everything, install everything and write your very first swagger docs. 06:14.990 --> 06:16.310 So that's it for this one. 06:16.310 --> 06:20.810 Go ahead, spend some time in reading at least 15 to 20 minutes, then come back into the next video. 06:20.810 --> 06:24.290 Let's go ahead and write some awesome documentation together.