1 00:00:00,290 --> 00:00:02,670 Instructor: In this lecture, we will demonstrate how to 2 00:00:02,670 --> 00:00:07,670 implement OpenAPI for a Web API using existing libraries. 3 00:00:09,060 --> 00:00:09,893 Now in our specific demo 4 00:00:09,893 --> 00:00:11,490 (keyboard clicks) 5 00:00:11,490 --> 00:00:13,440 we will demonstrate this capability 6 00:00:13,440 --> 00:00:17,820 on ASP.NET Core using Visual Studio Code. 7 00:00:17,820 --> 00:00:21,720 Now this course is not an extensive .NET Core course 8 00:00:21,720 --> 00:00:23,900 and I don't expect you to follow everything 9 00:00:23,900 --> 00:00:25,475 you will see on the screen. 10 00:00:25,475 --> 00:00:27,150 What's important to me is 11 00:00:27,150 --> 00:00:31,170 that you will able to understand the general concepts 12 00:00:31,170 --> 00:00:34,530 of how to use the OpenAPI libraries 13 00:00:34,530 --> 00:00:37,013 and understand that with different platforms, 14 00:00:37,013 --> 00:00:39,450 this is more or less the same. 15 00:00:39,450 --> 00:00:40,533 So let's go. 16 00:00:42,210 --> 00:00:44,444 So we are going to start with a command prompt 17 00:00:44,444 --> 00:00:45,277 (mouse click) 18 00:00:45,277 --> 00:00:48,535 and we will create a new .NET project. 19 00:00:48,535 --> 00:00:53,535 (keyboard clicks) .NET new Web API 20 00:00:55,170 --> 00:01:00,170 and we now tell the .NET to create a new Web API project, 21 00:01:00,630 --> 00:01:01,830 which is exactly what we need 22 00:01:01,830 --> 00:01:05,550 because we are going to demonstrate Swagger on Web API. 23 00:01:05,550 --> 00:01:07,920 Great, so now we have what we need 24 00:01:07,920 --> 00:01:12,920 and let's now add the OpenAPI library we will be using. 25 00:01:13,590 --> 00:01:18,210 So: (typing) .NET add package 26 00:01:18,210 --> 00:01:22,323 and notice the very interesting name of the library: 27 00:01:23,220 --> 00:01:26,230 Swashbuckle.ASPNetCore 28 00:01:28,980 --> 00:01:32,640 There are some libraries for implementing OpenAPI 29 00:01:32,640 --> 00:01:35,684 for .NET Core, but this is the most common one. 30 00:01:35,684 --> 00:01:36,517 (keyboard clicks) 31 00:01:36,517 --> 00:01:37,983 So let's add the package. 32 00:01:40,860 --> 00:01:41,700 Great. 33 00:01:41,700 --> 00:01:45,540 Now let's open Visual Studio Code 34 00:01:45,540 --> 00:01:47,313 and examine what we have. 35 00:01:48,374 --> 00:01:50,957 (mouse clicks) 36 00:01:52,590 --> 00:01:55,350 So here we see the list of files 37 00:01:55,350 --> 00:01:59,466 that were created when we executed the .NET new. 38 00:01:59,466 --> 00:02:00,360 (mouse click) 39 00:02:00,360 --> 00:02:03,720 So if you will take a look here in the controller 40 00:02:03,720 --> 00:02:06,931 we see we have a Web API controller 41 00:02:06,931 --> 00:02:09,360 called ValuesController 42 00:02:09,360 --> 00:02:11,220 which exposes some actions. 43 00:02:11,220 --> 00:02:14,550 This is, these two are GET and POST 44 00:02:14,550 --> 00:02:17,700 and PUT and DELETE. 45 00:02:17,700 --> 00:02:20,080 We will focus on the first one this GET 46 00:02:20,080 --> 00:02:22,950 and as you can see it's a very simple action. 47 00:02:22,950 --> 00:02:25,620 It gets no parameter in the returns, 48 00:02:25,620 --> 00:02:29,280 a short string array with two items. 49 00:02:29,280 --> 00:02:32,580 So now let's try to run this sample just to make sure 50 00:02:32,580 --> 00:02:34,620 that everything is working fine. 51 00:02:34,620 --> 00:02:37,048 So first let's open the terminal here. 52 00:02:37,048 --> 00:02:38,460 (mouse clicks) 53 00:02:38,460 --> 00:02:42,360 Great, and now go here to the output (mouse clicks) 54 00:02:42,360 --> 00:02:45,300 and I will hit F-5 to tell visuals studio code 55 00:02:45,300 --> 00:02:46,683 to run the project. 56 00:02:47,730 --> 00:02:49,620 And you see that something is happening 57 00:02:49,620 --> 00:02:51,603 which is normally good, 58 00:02:52,440 --> 00:02:56,470 and I'll drag the browser page that was opened 59 00:02:56,470 --> 00:02:58,050 (mouse clicks) for my other monitor. 60 00:02:58,050 --> 00:03:00,600 Now this might look scary, but this is actually 61 00:03:00,600 --> 00:03:03,964 exactly what we expected because we are not going to browse 62 00:03:03,964 --> 00:03:06,720 to this address, which is a root address. 63 00:03:06,720 --> 00:03:09,150 We want to look at the API. (mouse clicks) 64 00:03:09,150 --> 00:03:11,950 So I'll take this address and add to it 65 00:03:13,260 --> 00:03:15,360 API slash values. (keyboard clicks) 66 00:03:15,360 --> 00:03:19,020 And you see that we've got the return value 67 00:03:19,020 --> 00:03:21,000 which was expected from the code. 68 00:03:21,000 --> 00:03:25,110 So let's take a look again at the code here, (mouse clicks) 69 00:03:25,110 --> 00:03:29,400 and you see that the API should have returned a string array 70 00:03:29,400 --> 00:03:32,370 with value one and value two (keyboard clicks) 71 00:03:32,370 --> 00:03:35,430 which is exactly what we've got. 72 00:03:35,430 --> 00:03:38,940 And now let's actually add a break point to make sure 73 00:03:38,940 --> 00:03:41,070 that the code here is actually 74 00:03:41,070 --> 00:03:43,260 executed by the browser. (mouse clicks) 75 00:03:43,260 --> 00:03:45,360 So we'll put the console here, (mouse clicks) 76 00:03:45,360 --> 00:03:49,080 and debug to the brick point, (mouse clicks) 77 00:03:49,080 --> 00:03:53,780 and let's go back to the browser (keyboard clicks) 78 00:03:54,660 --> 00:03:57,276 and hit 'refresh', (keyboard clicks) 79 00:03:57,276 --> 00:03:59,250 and you see that Visual Studio Code 80 00:03:59,250 --> 00:04:00,960 here (mouse clicks) is calling us. 81 00:04:00,960 --> 00:04:04,741 And yes, it stopped at this very line of code 82 00:04:04,741 --> 00:04:09,741 that contains the return new string with the two items. 83 00:04:10,080 --> 00:04:10,913 Okay, great. 84 00:04:10,913 --> 00:04:14,490 So the code is working, and we have a Web API. 85 00:04:14,490 --> 00:04:16,709 And now let's go to the more interesting part 86 00:04:16,709 --> 00:04:19,529 of adding the Swagger support. 87 00:04:19,529 --> 00:04:21,899 So let's stop this (keyboard clicks) 88 00:04:21,899 --> 00:04:24,720 and go to this file, the Startup.cs. 89 00:04:24,720 --> 00:04:27,780 Now Startup.cs is a very important file 90 00:04:27,780 --> 00:04:29,550 in the .NET Core environment 91 00:04:29,550 --> 00:04:31,830 and it sets the various services 92 00:04:31,830 --> 00:04:34,800 and configuration the application is going to use. 93 00:04:34,800 --> 00:04:36,990 Now I'm not going to go over the code 94 00:04:36,990 --> 00:04:39,450 because actually it's not very interesting for us. 95 00:04:39,450 --> 00:04:41,370 We just want to focus on the parts 96 00:04:41,370 --> 00:04:44,280 that are relevant for the Swagger support. 97 00:04:44,280 --> 00:04:46,200 So let's just do it. 98 00:04:46,200 --> 00:04:47,550 The first thing we are going to do 99 00:04:47,550 --> 00:04:52,550 is to add these two 'using' lines 100 00:04:52,680 --> 00:04:56,430 to add support for the reflection and IO Namespace. 101 00:04:56,430 --> 00:04:58,710 We are going to need it later. 102 00:04:58,710 --> 00:05:03,710 Next, we are going to add the following code segment 103 00:05:04,006 --> 00:05:08,010 (mouse clicks) here in the configured services method. 104 00:05:08,010 --> 00:05:10,020 And this is what we are adding. 105 00:05:10,020 --> 00:05:12,510 So what we actually tell here for .NET 106 00:05:12,510 --> 00:05:17,250 is be aware that there is a service called Swagger 107 00:05:17,250 --> 00:05:19,500 and you should be able to use it. 108 00:05:19,500 --> 00:05:23,070 Now by saying so we also define some options for Swagger, 109 00:05:23,070 --> 00:05:26,970 such as the title, the version, the description, 110 00:05:26,970 --> 00:05:31,440 and we are also adding support for XML comments right here 111 00:05:31,440 --> 00:05:34,023 which we will need later in this demonstration. 112 00:05:34,920 --> 00:05:36,960 So again, in the ConfigureServices 113 00:05:36,960 --> 00:05:41,070 we introduce the Swagger service to .NET Core. 114 00:05:41,070 --> 00:05:42,810 And now we need to fine-tune it 115 00:05:42,810 --> 00:05:45,469 and tell .NET exactly what it should do 116 00:05:45,469 --> 00:05:48,060 with this Swagger service. 117 00:05:48,060 --> 00:05:50,310 And to do that we are going to scroll down 118 00:05:50,310 --> 00:05:52,170 to this method, the Configure, (mouse clicks) 119 00:05:52,170 --> 00:05:56,280 and the Configure method configures various details 120 00:05:56,280 --> 00:05:57,870 about the application (mouse clicks) 121 00:05:57,870 --> 00:05:59,940 and we are going to configure now (mouse clicks) 122 00:05:59,940 --> 00:06:03,600 how exactly to use the Swagger service. (mouse clicks) 123 00:06:03,600 --> 00:06:06,420 So we are adding the following line of code: 124 00:06:06,420 --> 00:06:09,000 The first one is 'UseSwagger', 125 00:06:09,000 --> 00:06:10,680 which basically tells .NET 126 00:06:10,680 --> 00:06:12,810 'use the Swagger capabilities 127 00:06:12,810 --> 00:06:15,510 and generate the Swagger documentation 128 00:06:15,510 --> 00:06:17,370 and use Swagger UI', 129 00:06:17,370 --> 00:06:20,940 which adds support for the user interface of Swagger 130 00:06:20,940 --> 00:06:22,620 which we have already met. 131 00:06:22,620 --> 00:06:24,750 Now, note that part of this code 132 00:06:24,750 --> 00:06:26,935 is a definition of the exact location 133 00:06:26,935 --> 00:06:28,590 of this Swagger JSON. 134 00:06:28,590 --> 00:06:31,260 You probably remember the Swagger JSON. 135 00:06:31,260 --> 00:06:33,548 We saw its content and also explored 136 00:06:33,548 --> 00:06:36,930 some of its fields and we are going to have access 137 00:06:36,930 --> 00:06:39,404 to this file in this address. 138 00:06:39,404 --> 00:06:41,730 Now the last thing we need to do 139 00:06:41,730 --> 00:06:44,820 in order to tell .NET that we want to generate 140 00:06:44,820 --> 00:06:49,820 the XML documentation file is to open the 'csproj' file. 141 00:06:52,230 --> 00:06:55,290 This file manages the .NET project itself 142 00:06:55,290 --> 00:06:58,053 and we will need to add some configuration data to it. 143 00:06:59,997 --> 00:07:04,997 (keyboard sound) So I'll go here and add this configuration. 144 00:07:05,160 --> 00:07:07,260 Basically what we just told .NET 145 00:07:07,260 --> 00:07:09,840 is to generate the documentation file 146 00:07:09,840 --> 00:07:14,040 and to suppress some warnings that might result from it. 147 00:07:14,040 --> 00:07:15,270 So now let's save it (keyboard sounds) 148 00:07:15,270 --> 00:07:16,650 and let's close this file. 149 00:07:16,650 --> 00:07:19,050 We won't be needing it anymore. 150 00:07:19,050 --> 00:07:22,377 So this is a complete Startup CS file 151 00:07:22,377 --> 00:07:24,818 and now our project is ready to run 152 00:07:24,818 --> 00:07:28,980 and ready to support and actually use the Swagger. 153 00:07:28,980 --> 00:07:32,223 So let's hit F-5 and see what happens. 154 00:07:33,330 --> 00:07:35,530 So again, VS code is doing its magic 155 00:07:37,410 --> 00:07:39,150 a lot of movement down there 156 00:07:39,150 --> 00:07:43,770 and we've got the browser page with Arrow, 157 00:07:43,770 --> 00:07:47,850 but this time we are not going to access 'API/values'. 158 00:07:47,850 --> 00:07:49,653 Now we want to see the Swagger. 159 00:07:52,136 --> 00:07:53,400 So: '/Swagger' 160 00:07:53,400 --> 00:07:54,993 and see what we've got here. 161 00:07:57,713 --> 00:08:00,450 This is the Swagger documentation page 162 00:08:00,450 --> 00:08:02,340 automatically generated for us 163 00:08:02,340 --> 00:08:04,290 by the Swash Bucket Library. 164 00:08:04,290 --> 00:08:05,130 And as you can see, 165 00:08:05,130 --> 00:08:08,880 it looks exactly like the Swagger pages 166 00:08:08,880 --> 00:08:10,500 we saw in the previous demo. 167 00:08:10,500 --> 00:08:13,200 This is the exact same format 168 00:08:13,200 --> 00:08:17,340 with these colors, with the links, with the details. 169 00:08:17,340 --> 00:08:20,580 Here is a title that we defined in the code. 170 00:08:20,580 --> 00:08:21,810 This is a description. 171 00:08:21,810 --> 00:08:25,320 Here is the link to the Swagger JSON file 172 00:08:25,320 --> 00:08:28,440 and basically it looks exactly the same. 173 00:08:28,440 --> 00:08:31,920 So let's go back to the Startup cs (mouse click) 174 00:08:31,920 --> 00:08:34,799 just to summarize what exactly we did. 175 00:08:34,799 --> 00:08:37,530 So we added support for these two name spaces, 176 00:08:37,530 --> 00:08:39,240 Reflection and IO. 177 00:08:39,240 --> 00:08:42,270 We added this segment to support 178 00:08:42,270 --> 00:08:44,760 or to add the support to Swagger. 179 00:08:44,760 --> 00:08:47,250 And we add those two line of codes 180 00:08:47,250 --> 00:08:51,120 which defined how exactly we want to use Swagger. 181 00:08:51,120 --> 00:08:54,270 And also we added some configuration data 182 00:08:54,270 --> 00:08:56,400 to the project file. 183 00:08:56,400 --> 00:08:59,340 Now we are not done yet because if you will look again 184 00:08:59,340 --> 00:09:03,990 at the documentation page, we can see it is quite bland. 185 00:09:03,990 --> 00:09:07,080 There is no description, there are no examples. 186 00:09:07,080 --> 00:09:08,790 It basically only lays out 187 00:09:08,790 --> 00:09:12,150 the API and displays the various actions, 188 00:09:12,150 --> 00:09:14,340 but there are no explanation whatsoever. 189 00:09:14,340 --> 00:09:17,550 And we want documentation to explain the developer 190 00:09:17,550 --> 00:09:18,930 what exactly is happening 191 00:09:18,930 --> 00:09:22,110 and what is the purpose of its action. 192 00:09:22,110 --> 00:09:23,430 So let's do it now. 193 00:09:23,430 --> 00:09:26,803 I'll close this page. (mouse clicks) 194 00:09:27,990 --> 00:09:28,860 Stop it. (mouse clicks) 195 00:09:28,860 --> 00:09:31,530 And now let's go to the code. (mouse clicks) 196 00:09:31,530 --> 00:09:33,210 So this is our controller. 197 00:09:33,210 --> 00:09:34,980 And let's say I want to add 198 00:09:34,980 --> 00:09:38,013 a short description of this action. 199 00:09:38,940 --> 00:09:42,853 So this is what I need to do. (keyboard clicks) 200 00:09:44,190 --> 00:09:46,470 Using the three slashes shortcut. 201 00:09:46,470 --> 00:09:49,050 I've got now the XM documentation of this method. 202 00:09:49,050 --> 00:09:52,590 So all I need to do is to add a summary (keyboard clicks) 203 00:09:52,590 --> 00:09:57,590 which is 'Demo API for the REST API Course'. 204 00:09:58,710 --> 00:10:00,210 And let's not go any further. 205 00:10:00,210 --> 00:10:02,010 Just let's see if this is working. 206 00:10:02,010 --> 00:10:03,573 So again, F-5. 207 00:10:06,870 --> 00:10:10,653 Magic, magic, magic. Things are moving. 208 00:10:11,875 --> 00:10:16,875 (mouse clicks) And this is our page, Swagger, 209 00:10:18,000 --> 00:10:19,323 and look at this. 210 00:10:20,370 --> 00:10:23,520 So using the XM documentation format 211 00:10:23,520 --> 00:10:27,690 we can add a summary, remarks, parameters, examples, 212 00:10:27,690 --> 00:10:29,280 whatever we want. 213 00:10:29,280 --> 00:10:32,520 And this data will be automatically generated 214 00:10:32,520 --> 00:10:34,923 into the Swagger documentation. 215 00:10:35,790 --> 00:10:37,650 So what we've learned? 216 00:10:37,650 --> 00:10:40,770 We learned that we don't need to manually build 217 00:10:40,770 --> 00:10:42,510 the Swagger JSON file. 218 00:10:42,510 --> 00:10:45,690 It is built for us automatically using libraries. 219 00:10:45,690 --> 00:10:49,020 In this demo, we demonstrated it in .NET Core, 220 00:10:49,020 --> 00:10:51,660 but actually this exact same concept 221 00:10:51,660 --> 00:10:53,790 exists in other platforms as well. 222 00:10:53,790 --> 00:10:57,483 So feel free to use it in whatever platform you are using.