WEBVTT 00:03.360 --> 00:05.230 Hey there, everyone that they share. 00:05.230 --> 00:09.340 And in this video, we are going to talk about some of the configuration that you should be worried 00:09.340 --> 00:11.660 about when writing the documentation. 00:11.680 --> 00:16.750 Now, it is very important that you ask from your seniors or somebody who is guiding you that what kind 00:16.750 --> 00:19.420 of versions we are following up in this specification. 00:19.420 --> 00:25.990 For example, writing Swagger 2.0 and writing open API three point something is completely two different 00:25.990 --> 00:30.730 things and you have to follow the documentation and look into the guide for that particular thing. 00:30.760 --> 00:35.620 Now when you write open API 3.0, then whatever the link that I have given to you up here for these 00:35.620 --> 00:39.340 structures, they are actually all for the open API 3.0. 00:39.340 --> 00:43.810 But the moment if you write Swagger 2.0, that means you are following or you are following a little 00:43.810 --> 00:44.920 bit of the older structure. 00:44.920 --> 00:46.870 You need to look the documentation for that. 00:46.870 --> 00:48.970 So it is very important that you write that. 00:49.000 --> 00:51.130 Now again, these are similar versioning. 00:51.130 --> 00:57.340 So as soon as you write 3.0. something or 3.2. whatever the main idea is writing three dot in case you 00:57.340 --> 00:58.570 are using open API. 00:58.720 --> 01:00.460 So let's go ahead and work on with that. 01:00.460 --> 01:02.800 Let's open up our swagger dot yaml. 01:02.800 --> 01:06.430 This is where majority of the time we'll be spending a whole lot of our time. 01:06.430 --> 01:07.450 So let's go up there. 01:08.110 --> 01:10.390 By the way, from the right you can see the swagger file. 01:10.390 --> 01:15.520 So it is really important that you can easily find out that in which file I am working on or I am writing. 01:15.520 --> 01:19.150 And we also don't need too much of this one so we can just go away with that. 01:19.270 --> 01:22.990 So the first thing we are going to write is what kind of open API version we are following. 01:22.990 --> 01:29.530 So obviously we are following 3.00.021 or you write zero. 01:29.530 --> 01:31.000 That is almost kind of a same. 01:31.000 --> 01:32.560 There are very minor differences. 01:32.560 --> 01:33.730 It's not going to break anything. 01:33.730 --> 01:34.960 So that is one thing. 01:34.960 --> 01:38.680 As soon as you do this, you already know that this is how it works on. 01:38.710 --> 01:43.690 As soon as you reload, this is going to say, okay, now you have selected your API version, you know 01:43.690 --> 01:46.180 about it, but you haven't mentioned anything else further. 01:46.300 --> 01:48.900 So the first thing that you'll be writing is the info. 01:48.910 --> 01:50.560 This is all about information. 01:50.560 --> 01:52.180 Make sure you keep an eye on the indentation. 01:52.180 --> 01:53.650 This is super important for it. 01:53.800 --> 01:56.920 The first thing that goes in this is actually the title. 01:56.920 --> 02:02.800 The title define what is this app or this application and what it's going to be using for. 02:02.800 --> 02:06.820 So we'll be using this for is learn, express and swagger. 02:06.820 --> 02:07.750 That's what it is. 02:07.750 --> 02:10.630 And then probably I'll write learn code online. 02:10.630 --> 02:18.130 So this is what we'll be doing up now after that it comes up is the description and I am known for the 02:18.130 --> 02:20.410 typos, but hopefully I didn't meet this time. 02:20.410 --> 02:31.030 So if we're going to simply say that a course segment about writing docs, that sounds great. 02:31.030 --> 02:35.950 Now after that, you can also go ahead and define the version that what kind of version of this documentation 02:35.950 --> 02:36.280 is. 02:36.280 --> 02:41.440 And people really it makes a lot of sense to properly define it and follow some kind of standard with 02:41.440 --> 02:41.800 that. 02:41.800 --> 02:48.910 So we're going to go for 1.0.1 because we have already one gone for the previous one or we can say 1.1.0 02:48.910 --> 02:50.440 because we are modifying it a lot. 02:50.440 --> 02:53.170 But again, make sure you show some consistency up here. 02:53.170 --> 02:57.790 Now, once we are done with that, then comes the two important thing, which is inside this one, which 02:57.790 --> 02:58.660 is contact. 02:59.140 --> 03:04.810 So inside this contact you can write your email so people can actually reach out for that one. 03:04.810 --> 03:06.670 So you always have to write. 03:06.940 --> 03:11.380 It's not compulsory, but you don't have to wrap that around inside the double code or anything. 03:11.380 --> 03:13.870 We are into the segment of YAML. 03:14.290 --> 03:17.710 It is notoriously known for sometimes we use these codes, sometimes we don't. 03:17.710 --> 03:19.240 Majority of the time we don't code. 03:19.270 --> 03:21.010 This is just a specification. 03:21.010 --> 03:22.060 That's why we are here. 03:22.330 --> 03:24.490 Majority of the time you won't be seeing it. 03:24.520 --> 03:27.400 A couple of places are still there where you will find that. 03:27.400 --> 03:33.250 So let's just say if I have an email of I don't have this one, but probably so let's go ahead and use 03:33.250 --> 03:33.910 this one. 03:33.910 --> 03:36.070 And also you can use a URL. 03:36.070 --> 03:38.080 So I'm going to go ahead and use a URL. 03:38.080 --> 03:41.350 Now, in this case, I have to use the double code again. 03:41.350 --> 03:42.310 I'm not making this up. 03:42.310 --> 03:44.020 This is all mentioned in the standards. 03:44.020 --> 03:51.070 So as soon as I do this, this you are going to see that this provides you a little bit of the information. 03:51.190 --> 03:53.170 So this is an Learn Express. 03:53.170 --> 03:55.510 We are following the open API standard three. 03:55.510 --> 03:56.860 This is 1.1. 03:56.860 --> 03:58.390 A whole lot of good information. 03:58.390 --> 04:02.200 You can contact the developer on this website or send the email. 04:02.290 --> 04:03.190 It's up to you. 04:03.190 --> 04:07.390 If you don't want to show up your email totally on you and you can go ahead and skip this part. 04:07.570 --> 04:07.870 Okay. 04:07.870 --> 04:08.410 Moving on. 04:08.410 --> 04:13.270 Now that you know about, these are compulsory things to be done after that comes up is a very interesting 04:13.270 --> 04:14.770 thing, which is servers. 04:14.770 --> 04:20.500 Now, this is something really important for you if you are working in any of the organization, let's 04:20.500 --> 04:22.120 just say I have a couple of servers. 04:22.120 --> 04:25.480 In fact, there are usually more than one production. 04:25.480 --> 04:28.510 There is a testing server sometimes even in between. 04:28.510 --> 04:30.160 So you have to mention all of them. 04:30.160 --> 04:38.890 Let's just say I want to write a setpiece column, slash, slash and I have a local host and Colon 4000 04:38.890 --> 04:43.090 and we are following the standard something like slash API slash V one. 04:43.630 --> 04:44.980 So this is what it is. 04:44.980 --> 04:47.770 And after that we can also write description. 04:47.770 --> 04:52.270 So make sure you pay attention on the indentation that I'm using, otherwise you'll mess it up. 04:52.270 --> 04:56.920 So description we're going to say for local host that's it. 04:56.920 --> 05:01.180 Now notice here very carefully if I go back and hit a reload it. 05:01.260 --> 05:02.140 Gives me this. 05:02.160 --> 05:04.530 My description comes just after this. 05:04.530 --> 05:05.880 And this is all what we have done. 05:05.880 --> 05:10.050 A common mistake that is being done is for the indentation, especially when it comes to this kind of 05:10.080 --> 05:10.730 structure. 05:10.740 --> 05:12.230 People like to go like this. 05:12.240 --> 05:16.860 If you are going to go for this this time, it has given me all these errors thanks to the extensions. 05:17.070 --> 05:22.920 But if it doesn't, make sure you try out your indentation and make sure you stay consistent with that. 05:23.100 --> 05:27.870 Now I'm going to go ahead and select this and I'm going to press my option shift and down arrow key 05:27.870 --> 05:31.110 to duplicate this kind of a shortcut or copy paste, whatever you like. 05:31.260 --> 05:33.720 Maybe I'm supporting the two versions. 05:33.720 --> 05:36.960 One is for HTTP and one is for HTTPS. 05:37.380 --> 05:44.730 This is a dash secure kind of, and this is dash regular. 05:44.850 --> 05:47.790 So these are the two versions that I'm supporting for my API. 05:47.790 --> 05:52.530 If I go back to the browser to reload now, I have a dropdown option of selecting this. 05:52.530 --> 05:58.410 Now I'm not going to be throughout the documentation B following the APIs and these stuff that I'm going 05:58.410 --> 05:59.250 to talk about. 05:59.250 --> 06:03.810 But yes, you can actually go ahead and provide all these options for internal documentation. 06:04.500 --> 06:09.900 But what I like to do more is probably you will be changing this one to V one and V two and this much 06:09.900 --> 06:13.620 of the dropdown sometimes can actually cause like this is too much. 06:13.620 --> 06:16.290 I want to have a little bit more of information now. 06:16.290 --> 06:19.920 Variables are supported in the YAML, but they have a different structure. 06:19.920 --> 06:24.570 So I'm going to go ahead and simply I'll copy this and I'll comment this out. 06:24.570 --> 06:29.850 So Control and Slash are the shortcut for commenting down or you can use the pound sign. 06:29.850 --> 06:31.920 So let's go ahead and use some form of variable. 06:31.920 --> 06:35.490 We don't need this much up here, so we don't need this URL. 06:35.550 --> 06:41.430 Now what happens is that you can first head the tab and you can define your variables like this. 06:41.700 --> 06:46.020 Now in the variables, what we're going to say, you can name your variable whatever you like. 06:46.020 --> 06:47.190 It's up to you. 06:47.340 --> 06:48.930 Make sure you indent it first. 06:48.930 --> 06:51.390 I'm going to first say this is my protocol. 06:52.320 --> 06:54.330 Now you don't need to specifically name it protocol. 06:54.330 --> 06:55.350 You can name it Superman. 06:55.350 --> 06:57.270 But hey, let's make some sense up here. 06:57.300 --> 07:01.980 Now, in the protocol you can define your variables, but I would prefer to have enemies in case you 07:01.980 --> 07:03.240 don't know about enemies. 07:03.240 --> 07:05.160 Enemies actually restrict your options. 07:05.160 --> 07:07.530 Especially I always give the example of airlines. 07:07.530 --> 07:11.700 Airlines always have three options aisle middle and the window seat. 07:11.700 --> 07:13.170 So we want to restrict the options. 07:13.170 --> 07:15.600 In such cases, enemies are the best friend. 07:15.600 --> 07:16.220 Happy here. 07:16.560 --> 07:18.600 Okay, we want to give two options up here. 07:18.600 --> 07:24.510 The first one being this is for version one and the second one being this is going to be for version 07:24.510 --> 07:25.020 two. 07:25.110 --> 07:27.690 Okay, now how I can use this protocol up here. 07:27.750 --> 07:30.840 That is exactly why we have used the double quotes up here. 07:30.930 --> 07:33.780 Variables usually go in the format of this one. 07:33.870 --> 07:40.320 I can go ahead and remove this, remove this V one here because this is the protocol actually this should 07:40.320 --> 07:41.610 be version protocol. 07:41.610 --> 07:43.320 It's going to come up in a second. 07:43.320 --> 07:46.950 So let's change this one to version and I'm going to copy that. 07:47.520 --> 07:51.360 And we are going to remove this, use the curly braces and paste this. 07:51.360 --> 07:52.500 Now, this is version. 07:52.500 --> 07:56.130 Now also what we can do is we can make a copy of this. 07:56.130 --> 07:58.230 So I'm going to go ahead and make a copy of this. 07:58.350 --> 08:03.020 Now, instead of the version, I'm going to say protocol, declare it first or later. 08:03.040 --> 08:04.080 Doesn't really matter. 08:04.230 --> 08:12.690 Now, in this case, I want to restrict the users option to HTTP and I'm going to go ahead and say HTTPS. 08:13.500 --> 08:16.260 Now, obviously, we need to change the protocol up here. 08:16.260 --> 08:18.000 So there we go, just like this. 08:18.000 --> 08:20.190 And we simply go ahead and say protocol. 08:20.190 --> 08:23.070 Now, this is just a bad example that I'm giving you now. 08:23.070 --> 08:27.540 It doesn't say secure or anything because you can go ahead and change this or you can inject your variable. 08:27.570 --> 08:33.150 Another kind of a variable up here that says secure or regular, you can go ahead and do that. 08:33.180 --> 08:34.170 I'll save this one. 08:34.170 --> 08:36.090 Let's go back up here and hit reload. 08:36.090 --> 08:41.370 And you can see that now we have some of the server variables available and you can also mention the 08:41.370 --> 08:42.090 defaults. 08:42.090 --> 08:43.980 We will understand that in the next video. 08:43.980 --> 08:46.560 But right now I want to select the HTTPS. 08:46.560 --> 08:48.990 So my protocol, so this is the computed URL. 08:48.990 --> 08:53.310 And again, I didn't do it so I could actually automatically does all of this and gives me all that 08:53.310 --> 08:53.610 option. 08:53.610 --> 08:55.620 Now I select V two so it gives me v two. 08:55.620 --> 08:57.870 I can go ahead and select v one, it selects v one. 08:57.870 --> 09:00.630 Now I haven't mentioned what should be the default selection. 09:00.630 --> 09:03.390 That's why it's asking me all the time to select one. 09:03.390 --> 09:05.580 But you get the idea that how this is being done. 09:05.580 --> 09:08.910 So this is the basics of how things are being done. 09:09.090 --> 09:13.560 So I told you this is going to be really simple and we are going to understand each and every line of 09:13.560 --> 09:14.580 this documentation. 09:14.580 --> 09:19.080 This is going to be a part of your job, and that's why I'm paying so much of attention on this one. 09:19.260 --> 09:19.500 Okay. 09:19.590 --> 09:24.720 I'll still keep these servers so that you can later on come on to this file and can see at a quick glance 09:24.720 --> 09:26.100 that how things are being done. 09:26.100 --> 09:27.360 That's it for this one. 09:27.360 --> 09:32.730 Next in the next video, we're going to talk about some of the security that you can have for your documentation. 09:33.270 --> 09:35.610 So let's go ahead and catch up in the next video.