1 00:00:00,000 --> 00:00:03,870 -: Okay, so now, let's see a demo of OpenAPI. 2 00:00:03,870 --> 00:00:06,870 And in this lecture we will see two demos. 3 00:00:06,870 --> 00:00:11,310 The first one is this, The Swagger Pet Store. 4 00:00:11,310 --> 00:00:15,330 Pet Store is a fictional pet store, obviously, 5 00:00:15,330 --> 00:00:18,333 created by Swagger to demonstrate how the Swagger 6 00:00:18,333 --> 00:00:20,430 documentation looks like. 7 00:00:20,430 --> 00:00:25,430 So let's click this link, and this is how it's look like. 8 00:00:25,470 --> 00:00:28,140 Now this is a typical open API documentation 9 00:00:28,140 --> 00:00:29,790 and what you see here is of course 10 00:00:29,790 --> 00:00:34,110 the title, the version, some general information. 11 00:00:34,110 --> 00:00:37,680 And the really interesting part is this one. 12 00:00:37,680 --> 00:00:42,680 Here you see a list of APIs or endpoints that you can use. 13 00:00:43,410 --> 00:00:46,230 Now note that for every endpoint, 14 00:00:46,230 --> 00:00:49,140 you see the verb, POST, PUT, get, 15 00:00:49,140 --> 00:00:50,463 here is a DELETE. 16 00:00:51,480 --> 00:00:55,170 All of them are grouped under PET 17 00:00:55,170 --> 00:00:56,850 with some short description. 18 00:00:56,850 --> 00:00:59,820 And if you will click this action 19 00:00:59,820 --> 00:01:03,330 then we'll get a full documentation 20 00:01:03,330 --> 00:01:05,370 about this specific endpoint. 21 00:01:05,370 --> 00:01:09,480 So we see here a description, we see an example 22 00:01:09,480 --> 00:01:13,860 of how it looks like, and we also get a list 23 00:01:13,860 --> 00:01:17,130 of the responses expected from this action. 24 00:01:17,130 --> 00:01:19,650 Now let's go to this action. 25 00:01:19,650 --> 00:01:23,580 This action, as we can see, it finds PETS by status. 26 00:01:23,580 --> 00:01:27,690 This is a GET action and let's open it. 27 00:01:27,690 --> 00:01:30,720 And as we can see in the parameters section 28 00:01:30,720 --> 00:01:34,590 there is a list of what are the parameters we can use. 29 00:01:34,590 --> 00:01:36,690 Remember that we are looking for a pet 30 00:01:36,690 --> 00:01:41,690 by status and the statuses are available, pending or sold. 31 00:01:42,660 --> 00:01:45,900 And what kind of responses can, can we expect? 32 00:01:45,900 --> 00:01:47,970 So there is of course the 200, 33 00:01:47,970 --> 00:01:51,060 which means that the operation was successful and 400, 34 00:01:51,060 --> 00:01:52,680 which means there was some problem 35 00:01:52,680 --> 00:01:54,540 with processing the request. 36 00:01:54,540 --> 00:01:58,080 Now notice this button. 37 00:01:58,080 --> 00:02:00,582 They try it out, so click it 38 00:02:00,582 --> 00:02:04,740 and now we can execute the request. 39 00:02:04,740 --> 00:02:05,853 How do we do that? 40 00:02:07,020 --> 00:02:10,080 Let's pick some status from the list. 41 00:02:10,080 --> 00:02:14,820 I'll pick the available and click execute. 42 00:02:14,820 --> 00:02:16,113 Now see what happens. 43 00:02:19,860 --> 00:02:24,330 So Swagger executed the endpoint and called it 44 00:02:24,330 --> 00:02:25,950 this is what it called. 45 00:02:25,950 --> 00:02:29,310 So this is a cool command and get 46 00:02:29,310 --> 00:02:34,310 and this API with a parameter that we specified. 47 00:02:34,350 --> 00:02:37,110 And also, since the response content type here 48 00:02:37,110 --> 00:02:39,030 is application XML. 49 00:02:39,030 --> 00:02:42,990 This is the header that was sent to the API saying 50 00:02:42,990 --> 00:02:47,850 that the expected format is application XML. 51 00:02:47,850 --> 00:02:51,930 This is the actual URL of the endpoint that was accessed. 52 00:02:51,930 --> 00:02:55,350 And this is the response that we've got. 53 00:02:55,350 --> 00:02:57,060 So you can see here a list 54 00:02:57,060 --> 00:03:00,900 of pets that were returned by the server. 55 00:03:00,900 --> 00:03:04,053 And as you can see, this is in an XML format. 56 00:03:04,920 --> 00:03:06,570 Now let's go 57 00:03:06,570 --> 00:03:11,190 to this dropdown list and pick application/JSON 58 00:03:11,190 --> 00:03:13,710 as the format we would like to get from the server. 59 00:03:13,710 --> 00:03:15,963 And click execute again. 60 00:03:19,931 --> 00:03:22,140 And again the request was successful. 61 00:03:22,140 --> 00:03:23,877 You see the response code here 62 00:03:23,877 --> 00:03:27,930 and the response body now contains JSON format. 63 00:03:27,930 --> 00:03:32,610 So you see that the format was set using this dropdown. 64 00:03:32,610 --> 00:03:33,930 And as you can see here 65 00:03:33,930 --> 00:03:36,750 the header that was sent to the server said 66 00:03:36,750 --> 00:03:40,383 that we now want the response to be in JSON format. 67 00:03:42,297 --> 00:03:45,990 Now the interesting part here is that not a single line 68 00:03:45,990 --> 00:03:49,920 of code was written in order to create this test bed 69 00:03:49,920 --> 00:03:53,340 this test client, it is generated automatically 70 00:03:53,340 --> 00:03:55,170 using Swagger. 71 00:03:55,170 --> 00:03:58,950 So this is how a typical Swagger documentation looks like. 72 00:03:58,950 --> 00:04:02,460 So again, we have a list of actions with the verbs. 73 00:04:02,460 --> 00:04:06,030 They are grouped by some kind of title 74 00:04:06,030 --> 00:04:09,180 and provide a very convenient user interface 75 00:04:09,180 --> 00:04:12,960 for reading the documentation and testing the API. 76 00:04:12,960 --> 00:04:15,420 So this is a field demo and this is nice. 77 00:04:15,420 --> 00:04:18,120 And let's go to the second one. 78 00:04:18,120 --> 00:04:22,050 So the second one is called Swagger Inspector. 79 00:04:22,050 --> 00:04:25,206 And what Swagger Inspector allows us to do is to 80 00:04:25,206 --> 00:04:27,480 provide an an API 81 00:04:27,480 --> 00:04:29,010 and Swagger will automatically 82 00:04:29,010 --> 00:04:31,950 generate buildbot documentation for this API 83 00:04:31,950 --> 00:04:35,100 just by inspecting the endpoints. 84 00:04:35,100 --> 00:04:37,800 So we will use the Inspector to generate documentation 85 00:04:37,800 --> 00:04:40,920 for the API we built in Beeceptor. 86 00:04:40,920 --> 00:04:42,423 So click this link. 87 00:04:46,740 --> 00:04:50,790 Great. And now let's go to Beeceptor 88 00:04:50,790 --> 00:04:52,540 and copy 89 00:04:54,120 --> 00:04:55,330 this full URL 90 00:04:57,030 --> 00:04:59,103 and click mocking rules. 91 00:05:00,150 --> 00:05:02,640 And let's memorize one of the API's here. 92 00:05:02,640 --> 00:05:04,560 I'll go for this one. 93 00:05:04,560 --> 00:05:07,413 API/v1/order. 94 00:05:08,400 --> 00:05:09,390 Great. 95 00:05:09,390 --> 00:05:12,610 So let's go to the Inspector 96 00:05:14,220 --> 00:05:19,220 and paste the URL /API/v1/order 97 00:05:23,550 --> 00:05:25,893 and click send. 98 00:05:28,890 --> 00:05:31,530 Now what we've got here is something that looks really 99 00:05:31,530 --> 00:05:32,910 similar to Postman. 100 00:05:32,910 --> 00:05:35,250 So we have the URL, we have the response 101 00:05:35,250 --> 00:05:37,440 and we have some data about the request. 102 00:05:37,440 --> 00:05:40,863 But the more interesting part is right here. 103 00:05:41,700 --> 00:05:43,620 Now what's happening here is 104 00:05:43,620 --> 00:05:48,210 that the Swagger Inspector shows us what request we made 105 00:05:48,210 --> 00:05:50,880 and we can convert this request to Swagger 106 00:05:50,880 --> 00:05:53,310 or OpenAPI documentation. 107 00:05:53,310 --> 00:05:55,290 Now, in order to do that 108 00:05:55,290 --> 00:05:59,190 I'll mark the request that I want to convert 109 00:05:59,190 --> 00:06:04,190 to the documentation and click the create API definition. 110 00:06:04,500 --> 00:06:08,340 Now, if this is your first time visiting the Inspector site 111 00:06:08,340 --> 00:06:10,770 then you will be asked to sign up. 112 00:06:10,770 --> 00:06:12,270 So I'll skip this part. 113 00:06:12,270 --> 00:06:13,800 I am already signed up. 114 00:06:13,800 --> 00:06:16,380 So sign up to the Inspector 115 00:06:16,380 --> 00:06:20,100 and then come back to the site and do it again. 116 00:06:20,100 --> 00:06:23,740 And after you do it, click the create API definition 117 00:06:25,410 --> 00:06:27,090 and the definition was created 118 00:06:27,090 --> 00:06:31,190 and it is hosted in a website called SwaggerHub. 119 00:06:32,550 --> 00:06:34,563 So let's go to SwaggerHub. 120 00:06:38,010 --> 00:06:41,310 And now SwaggerHub asks us if we want to 121 00:06:41,310 --> 00:06:44,820 define some basic information about this documentation. 122 00:06:44,820 --> 00:06:49,723 So let's give it a name and we will call it demo-rest-api 123 00:06:51,120 --> 00:06:55,030 and the version, let's say it's version one 124 00:06:56,130 --> 00:07:00,123 and let's make it public and import OpenAPI. 125 00:07:03,270 --> 00:07:05,850 So now we have this Swagger documentation ready 126 00:07:05,850 --> 00:07:07,830 and we can even edit it. 127 00:07:07,830 --> 00:07:10,980 So look here at the right hand side 128 00:07:10,980 --> 00:07:13,530 of the screen so you can see a reflection 129 00:07:13,530 --> 00:07:16,020 of how exactly the documentation will look like 130 00:07:16,020 --> 00:07:17,850 for the developers using it. 131 00:07:17,850 --> 00:07:19,800 So we have here a default title 132 00:07:19,800 --> 00:07:21,870 which is not very informative. 133 00:07:21,870 --> 00:07:25,290 So you can modify it right here in the documentation. 134 00:07:25,290 --> 00:07:30,290 And let's change it to demo API for the REST API course. 135 00:07:35,520 --> 00:07:39,750 And you can see that it'll change right here. 136 00:07:39,750 --> 00:07:42,690 Let's also change the description. 137 00:07:42,690 --> 00:07:47,690 This is a demo API created for the REST API course. 138 00:07:53,790 --> 00:07:57,330 And again, we see it right here. 139 00:07:57,330 --> 00:08:00,360 And here you can see the action 140 00:08:00,360 --> 00:08:02,460 that we've created the documentation for. 141 00:08:02,460 --> 00:08:03,870 And if we'll click it 142 00:08:03,870 --> 00:08:07,980 we'll see exactly what we saw before at the pet store. 143 00:08:07,980 --> 00:08:11,790 So we have the expected response code 144 00:08:11,790 --> 00:08:14,970 we have an example of what is returned from the API 145 00:08:14,970 --> 00:08:18,090 and everything looks just the same. 146 00:08:18,090 --> 00:08:20,190 So this was a short demo 147 00:08:20,190 --> 00:08:24,780 of how to use the Swagger website and the Swagger Inspector. 148 00:08:24,780 --> 00:08:26,340 And now let's move on 149 00:08:26,340 --> 00:08:30,900 and explore the format of the Swagger documentation.