1 00:00:00,300 --> 00:00:02,940 Instructor: So let's go back to the Petstore, 2 00:00:02,940 --> 00:00:06,030 and if you look closely at the documentation page, 3 00:00:06,030 --> 00:00:08,370 you can see here a link. 4 00:00:08,370 --> 00:00:12,420 Now, this link ends with swagger.json. 5 00:00:12,420 --> 00:00:14,640 So, swagger.json is the name 6 00:00:14,640 --> 00:00:17,010 of the documentation file generated either 7 00:00:17,010 --> 00:00:20,820 by Swagger itself or by the Swagger library used 8 00:00:20,820 --> 00:00:23,010 for the specific platform you are using. 9 00:00:23,010 --> 00:00:25,380 So, we want to look closely at this file. 10 00:00:25,380 --> 00:00:29,700 So, let's download it to our computer, 11 00:00:29,700 --> 00:00:32,130 right click and save link as, 12 00:00:32,130 --> 00:00:37,130 and let's save it in our downloads folder and click it. 13 00:00:40,110 --> 00:00:45,110 So, in my PC, JSON files are opened in VS Code. 14 00:00:46,350 --> 00:00:47,850 You may be using some other tools, 15 00:00:47,850 --> 00:00:49,590 but it doesn't really matter. 16 00:00:49,590 --> 00:00:52,980 What we want to do is to explore this file, 17 00:00:52,980 --> 00:00:55,650 and understand what, exactly, it contains. 18 00:00:55,650 --> 00:00:59,040 Now, it might seem a very long and complex file, 19 00:00:59,040 --> 00:01:00,660 but as you will see in a minute, 20 00:01:00,660 --> 00:01:03,150 it's actually quite simple and basic file, 21 00:01:03,150 --> 00:01:05,550 and very, very easy to understand. 22 00:01:05,550 --> 00:01:07,680 So, let's start, go over it. 23 00:01:07,680 --> 00:01:10,260 First we have the Info field, 24 00:01:10,260 --> 00:01:14,370 which contains some general information about the API. 25 00:01:14,370 --> 00:01:16,800 So, we have a description, this is a sample server, 26 00:01:16,800 --> 00:01:20,430 petstore, petstore server, et cetera, et cetera. 27 00:01:20,430 --> 00:01:22,770 We have the title, we have the version, 28 00:01:22,770 --> 00:01:24,690 we have the terms of service, 29 00:01:24,690 --> 00:01:27,090 some contact email and the license. 30 00:01:27,090 --> 00:01:30,240 And if you will go to the documentation page 31 00:01:30,240 --> 00:01:33,240 on the Swagger website, then you can see 32 00:01:33,240 --> 00:01:36,960 that this data is exactly what is displayed right here. 33 00:01:36,960 --> 00:01:39,180 This is the title, this is the version. 34 00:01:39,180 --> 00:01:41,910 This is the descriptions that we saw. 35 00:01:41,910 --> 00:01:44,970 Here is a link to the terms of services, 36 00:01:44,970 --> 00:01:47,940 and the license, and the contact. 37 00:01:47,940 --> 00:01:50,670 So, everything is reflected quite easily 38 00:01:50,670 --> 00:01:52,713 in the documentation website itself. 39 00:01:54,270 --> 00:01:56,610 So, let's go back to the file, too, 40 00:01:56,610 --> 00:01:58,530 and let's skip here a little bit 41 00:01:58,530 --> 00:02:02,250 and go to the path found in the file. 42 00:02:02,250 --> 00:02:06,720 So, each entry in the passage contains a single endpoint 43 00:02:06,720 --> 00:02:08,763 and the first endpoint we see here 44 00:02:08,763 --> 00:02:12,543 is a pet endpoint with a POST verb. 45 00:02:13,470 --> 00:02:18,470 Now, what we see about this endpoint is, first, its tag. 46 00:02:18,900 --> 00:02:21,630 So, the tag here is pet, 47 00:02:21,630 --> 00:02:25,443 and now let's skip back to the documentation website, 48 00:02:26,820 --> 00:02:30,750 and you can see here that this is the endpoint. 49 00:02:30,750 --> 00:02:34,650 As you remember, it is called pet with the POST verb, 50 00:02:34,650 --> 00:02:39,650 and remember that the tag that we have, a tag named pet, 51 00:02:40,950 --> 00:02:44,730 the tag is used here to group the various endpoints 52 00:02:44,730 --> 00:02:46,200 into specific titles. 53 00:02:46,200 --> 00:02:49,650 So, the pet here, is the pet here. 54 00:02:49,650 --> 00:02:54,650 So, we know that this endpoint is under the pet tag. 55 00:02:56,880 --> 00:02:59,490 Okay, so let's continue reading this file. 56 00:02:59,490 --> 00:03:02,610 So, as a summary, we see that this endpoint is used 57 00:03:02,610 --> 00:03:05,730 to add a new pet to the store, 58 00:03:05,730 --> 00:03:10,477 and that it consumes and produces either JSON or XML, 59 00:03:11,850 --> 00:03:14,580 and that there is a single parameter 60 00:03:14,580 --> 00:03:16,410 in the body of the request, 61 00:03:16,410 --> 00:03:18,840 and this is a description of it, 62 00:03:18,840 --> 00:03:22,560 and for the response we can expect a 405, 63 00:03:22,560 --> 00:03:24,303 meaning Invalid Input. 64 00:03:26,670 --> 00:03:29,940 So, to summarize, this is, this part, 65 00:03:29,940 --> 00:03:34,940 is a documentation of a single endpoint in the API. 66 00:03:35,400 --> 00:03:37,440 So, now let's go and see 67 00:03:37,440 --> 00:03:40,533 how all this data is reflected in the documentation page. 68 00:03:43,140 --> 00:03:46,470 So, as we said earlier, we can see here, 69 00:03:46,470 --> 00:03:49,560 the description specified in the documentation. 70 00:03:49,560 --> 00:03:54,120 Remember that the API gets and returns either JSON or XML. 71 00:03:54,120 --> 00:03:57,240 So, you can see it here, JSON or XML, 72 00:03:57,240 --> 00:03:58,930 and here for the response 73 00:03:59,880 --> 00:04:03,060 and this is the response code that can be expected 74 00:04:03,060 --> 00:04:04,230 when calling this API. 75 00:04:04,230 --> 00:04:08,400 Remember that we saw that a response code of 405 76 00:04:08,400 --> 00:04:09,573 can be expected. 77 00:04:10,560 --> 00:04:13,680 So, this is basically the basic structure 78 00:04:13,680 --> 00:04:15,540 of a Swagger JSON file, 79 00:04:15,540 --> 00:04:17,100 and using this file, 80 00:04:17,100 --> 00:04:20,100 you can generate a very professional looking 81 00:04:20,100 --> 00:04:22,890 documentation that will attract many developers. 82 00:04:22,890 --> 00:04:25,620 Now, the good news are that you don't really need 83 00:04:25,620 --> 00:04:29,100 to write this file by hand even though it's really simple. 84 00:04:29,100 --> 00:04:30,990 As we will see in the next lecture, 85 00:04:30,990 --> 00:04:33,543 there are many libraries that generate 86 00:04:33,543 --> 00:04:37,380 this Swagger JSON file for you from the API 87 00:04:37,380 --> 00:04:39,993 and saves you the need to write this file.