Instructor: In this lecture, we will demonstrate how to
implement OpenAPI for a Web API using existing libraries.
Now in our specific demo
(keyboard clicks)
we will demonstrate this capability
on ASP.NET Core using Visual Studio Code.
Now this course is not an extensive .NET Core course
and I don't expect you to follow everything
you will see on the screen.
What's important to me is
that you will able to understand the general concepts
of how to use the OpenAPI libraries
and understand that with different platforms,
this is more or less the same.
So let's go.
So we are going to start with a command prompt
(mouse click)
and we will create a new .NET project.
(keyboard clicks) .NET new Web API
and we now tell the .NET to create a new Web API project,
which is exactly what we need
because we are going to demonstrate Swagger on Web API.
Great, so now we have what we need
and let's now add the OpenAPI library we will be using.
So: (typing) .NET add package
and notice the very interesting name of the library:
Swashbuckle.ASPNetCore
There are some libraries for implementing OpenAPI
for .NET Core, but this is the most common one.
(keyboard clicks)
So let's add the package.
Great.
Now let's open Visual Studio Code
and examine what we have.
(mouse clicks)
So here we see the list of files
that were created when we executed the .NET new.
(mouse click)
So if you will take a look here in the controller
we see we have a Web API controller
called ValuesController
which exposes some actions.
This is, these two are GET and POST
and PUT and DELETE.
We will focus on the first one this GET
and as you can see it's a very simple action.
It gets no parameter in the returns,
a short string array with two items.
So now let's try to run this sample just to make sure
that everything is working fine.
So first let's open the terminal here.
(mouse clicks)
Great, and now go here to the output (mouse clicks)
and I will hit F-5 to tell visuals studio code
to run the project.
And you see that something is happening
which is normally good,
and I'll drag the browser page that was opened
(mouse clicks) for my other monitor.
Now this might look scary, but this is actually
exactly what we expected because we are not going to browse
to this address, which is a root address.
We want to look at the API. (mouse clicks)
So I'll take this address and add to it
API slash values. (keyboard clicks)
And you see that we've got the return value
which was expected from the code.
So let's take a look again at the code here, (mouse clicks)
and you see that the API should have returned a string array
with value one and value two (keyboard clicks)
which is exactly what we've got.
And now let's actually add a break point to make sure
that the code here is actually
executed by the browser. (mouse clicks)
So we'll put the console here, (mouse clicks)
and debug to the brick point, (mouse clicks)
and let's go back to the browser (keyboard clicks)
and hit 'refresh', (keyboard clicks)
and you see that Visual Studio Code
here (mouse clicks) is calling us.
And yes, it stopped at this very line of code
that contains the return new string with the two items.
Okay, great.
So the code is working, and we have a Web API.
And now let's go to the more interesting part
of adding the Swagger support.
So let's stop this (keyboard clicks)
and go to this file, the Startup.cs.
Now Startup.cs is a very important file
in the .NET Core environment
and it sets the various services
and configuration the application is going to use.
Now I'm not going to go over the code
because actually it's not very interesting for us.
We just want to focus on the parts
that are relevant for the Swagger support.
So let's just do it.
The first thing we are going to do
is to add these two 'using' lines
to add support for the reflection and IO Namespace.
We are going to need it later.
Next, we are going to add the following code segment
(mouse clicks) here in the configured services method.
And this is what we are adding.
So what we actually tell here for .NET
is be aware that there is a service called Swagger
and you should be able to use it.
Now by saying so we also define some options for Swagger,
such as the title, the version, the description,
and we are also adding support for XML comments right here
which we will need later in this demonstration.
So again, in the ConfigureServices
we introduce the Swagger service to .NET Core.
And now we need to fine-tune it
and tell .NET exactly what it should do
with this Swagger service.
And to do that we are going to scroll down
to this method, the Configure, (mouse clicks)
and the Configure method configures various details
about the application (mouse clicks)
and we are going to configure now (mouse clicks)
how exactly to use the Swagger service. (mouse clicks)
So we are adding the following line of code:
The first one is 'UseSwagger',
which basically tells .NET
'use the Swagger capabilities
and generate the Swagger documentation
and use Swagger UI',
which adds support for the user interface of Swagger
which we have already met.
Now, note that part of this code
is a definition of the exact location
of this Swagger JSON.
You probably remember the Swagger JSON.
We saw its content and also explored
some of its fields and we are going to have access
to this file in this address.
Now the last thing we need to do
in order to tell .NET that we want to generate
the XML documentation file is to open the 'csproj' file.
This file manages the .NET project itself
and we will need to add some configuration data to it.
(keyboard sound) So I'll go here and add this configuration.
Basically what we just told .NET
is to generate the documentation file
and to suppress some warnings that might result from it.
So now let's save it (keyboard sounds)
and let's close this file.
We won't be needing it anymore.
So this is a complete Startup CS file
and now our project is ready to run
and ready to support and actually use the Swagger.
So let's hit F-5 and see what happens.
So again, VS code is doing its magic
a lot of movement down there
and we've got the browser page with Arrow,
but this time we are not going to access 'API/values'.
Now we want to see the Swagger.
So: '/Swagger'
and see what we've got here.
This is the Swagger documentation page
automatically generated for us
by the Swash Bucket Library.
And as you can see,
it looks exactly like the Swagger pages
we saw in the previous demo.
This is the exact same format
with these colors, with the links, with the details.
Here is a title that we defined in the code.
This is a description.
Here is the link to the Swagger JSON file
and basically it looks exactly the same.
So let's go back to the Startup cs (mouse click)
just to summarize what exactly we did.
So we added support for these two name spaces,
Reflection and IO.
We added this segment to support
or to add the support to Swagger.
And we add those two line of codes
which defined how exactly we want to use Swagger.
And also we added some configuration data
to the project file.
Now we are not done yet because if you will look again
at the documentation page, we can see it is quite bland.
There is no description, there are no examples.
It basically only lays out
the API and displays the various actions,
but there are no explanation whatsoever.
And we want documentation to explain the developer
what exactly is happening
and what is the purpose of its action.
So let's do it now.
I'll close this page. (mouse clicks)
Stop it. (mouse clicks)
And now let's go to the code. (mouse clicks)
So this is our controller.
And let's say I want to add
a short description of this action.
So this is what I need to do. (keyboard clicks)
Using the three slashes shortcut.
I've got now the XM documentation of this method.
So all I need to do is to add a summary (keyboard clicks)
which is 'Demo API for the REST API Course'.
And let's not go any further.
Just let's see if this is working.
So again, F-5.
Magic, magic, magic. Things are moving.
(mouse clicks) And this is our page, Swagger,
and look at this.
So using the XM documentation format
we can add a summary, remarks, parameters, examples,
whatever we want.
And this data will be automatically generated
into the Swagger documentation.
So what we've learned?
We learned that we don't need to manually build
the Swagger JSON file.
It is built for us automatically using libraries.
In this demo, we demonstrated it in .NET Core,
but actually this exact same concept
exists in other platforms as well.
So feel free to use it in whatever platform you are using.