0:02 / 16:13 Swagger is a set of tools that helps the developers to generate the user interface
in order to document and test the restful web API services.
Swagger is built on top of OpenAPI. OpenAPI is the specification
that helps the developers to write web API specification in JSON format.
By using that JSON, some tools such as Swagger or NSwag can understand the structure of web API services,
can understand what request details are to be sent to a service, and what is the response structure, and
accordingly, they can generate the client-side code.
For example, by using Swagger, you can generate the user interface that is used to test the web API services, and
also by using NSwagger, you can generate the client-side code for Angular and React, etc.
So that in those Angular or React applications, you can consume the web API services.
There is another tool here, swashbuckle.asp.net core.
It is a framework that works based on Swagger that helps the .NET developers to integrate Swagger in ASP.NET Core.
So as a developer, you have to use these three together.
Swashbuckle works based on Swagger, and Swagger works based on OpenAPI.
OpenAPI is the specification. It is not any library or framework.
But whereas Swagger is a set of tools that works based on OpenAPI specification,
Swashbuckle is used to integrate Swagger easily in ASP.NET Core.
So as a developer of ASP.NET Core web API application,
you can use the Swagger UI to test the services that you develop,
and also can provide interactive documentation for the consumers of your web API services.
Nowadays, it is pretty common to use Swagger or OpenAPI in almost all web API services.
Let me demonstrate.
At first, in order to use Swagger, you have to install some NuGet packages.
So right-click on the web API project, manage NuGet packages,
and go to the browse and search for microsoft.aspnetcore.openapi.
So select this package, microsoft.aspnetcore.openapi, select the same version.
So it lets you to use OpenAPI specifications in your web API application.
But it’s not only enough, you have to install Swagger.
But alternatively, if you try to install swashbuckle.aspnetcore package,
it automatically installs the Swagger package too.
So search for swashbuckle.aspnetcore.
So this is the package, swashbuckle.aspnetcore, and install the same.
See, it automatically installs the package swashbuckle.aspnetcore.swagger,
and also swaggergen and swaggerui.
These three packages are required in order to use Swagger,
and the swashbuckle package automatically installs these packages.
And now we have to enable Swagger in our application.
So open up your program.cs file.
At the most top, you have to add Swagger services.
Hey, builder.services, I would like to add endpoint API explorer.
It enables the Swagger to read the endpoints of our application.
Here endpoints means the action methods of web API controllers.
For example, in cities controller, we have created all these action methods, right?
I mean, get, post, put, delete, etc.
So the Swagger can read those action method details,
and also enable another service called addSwaggerGen.
And this second service called addSwaggerGen
is responsible to add Swagger documentation in the current working project.
But these two services doesn’t enable the Swagger UI or Swagger JSON endpoints.
We have to add them explicitly in the request pipeline.
So after you call the builder.build,
here you can enable useSwagger and useSwaggerUI.
The purpose of useSwagger is it enables the endpoint for swagger.json file.
And this swagger.json file is the open API specification
that are generated about your web API controller endpoints.
Means it contains the information related to all the action methods of your controllers.
But based on this open API JSON file or Swagger JSON,
there should be a Swagger user interface
using which the users and developers can test the web API controllers.
Means we can send the requests and get the responses directly in the web page.
So for that purpose, we have to use useSwagger UI.
So at first, the Swagger has to read all the endpoints,
that means all the action methods of controllers.
So that is the purpose of the first method.
Based on that endpoints, it has to automatically generate open API specification.
And the same has to be exposed as a JSON file.
And that is the purpose of useSwagger.
And based on that Swagger.json, there should be Swagger UI
to send requests and get the response directly in the web page itself.
That is the purpose of useSwagger UI.
So all these four methods are interconnected.
They work on top of the other.
And notice there is no any particular changes in the controller.
So they remain same.
Let’s run the application now.
Now the default URL is api/test.
We don’t want it.
And we have to change the launch URL.
So go to your launch settings.json file.
And set the launch URL as Swagger.
That means the default URL will be HTTPS localhost,
the port number, for example, 7221 slash Swagger.
OK, let’s try again.
OK, it may take a little bit of time to effect
because the Kestrel window that is running on background
may take the changes of launch settings.json file a little late.
Let’s run one more time.
Now the URL has been changed here.
Localhost 7221, that is the port number of my application,
slash Swagger.
The index.html is automatically added to the path.
So the actual URL you can consider is localhost, port number, slash Swagger.
Swagger is the path here.
And as you can notice, it provides a built-in documentation
for all WebAPI controllers and its action methods.
See, it has detected that we have created two WebAPI controllers, cities and test.
And under cities controller, we have five endpoints.
That means five action methods.
And one for test controller.
So if you click on either of these, for example, get,
you can click anywhere.
And this is the sample output from that API.
So if you make a get request at this path,
you must get the corresponding response.
A JSON array with cities information.
So if you click on try it out and click on execute,
you can actually send a request.
So it has sent a get request at this URL.
And the headers that it sent is accept text by plane.
This is a request header.
And this is the final full request URL.
And the server has received the request
and provided this particular data as a response,
which includes the complete data from database.
You can also add the breakpoint if required.
For example, go to your cities controller,
get cities action method, add a breakpoint.
And run again.
Click on execute one more time.
So another request is sent.
It is just like running that URL on the normal browser or postman.
So it works in the same way.
Only the difference is the actual response that you return here
will be received and displayed in the Swagger UI itself
instead of displaying in the postman.
That’s the only difference.
So how does it actually benefit for developers and users?
The users can get to know what are the available endpoints,
the corresponding URLs, request and response types,
what parameters should be passed,
and what kind of response data they can expect.
For example, here the users can know that,
okay, we have to pass a city ID value,
then we will get the corresponding city details.
So it is the interactive documentation for the users.
And even developers can test their own web API services
to ensure whether it is working correctly.
For example, as a web API developer,
instead of you wait for another developer
create an Angular application or React application
and send a request to your web API controller,
then encounter some particular error or bug in your web API,
then you got a ticket from him,
and then you find out the actual reason of the problem.
Instead of this longer process,
you can quickly test your own services
and ensure whether it works correctly as expected
for all the test cases.
So it is interactive test tool.
It’s not unit testing,
but it seems to be interactive integration testing.
Because if you send a request,
the real code is being executed.
So it helps the developers to test their own services
and helps the users to know
the information related to endpoints
and test them from their side.
Only the thing that you have to do to enable Swagger
is install essential packages,
that is swashbuckle.aspnetcore
and microsoft.aspnetcore.openapi
and add these two services into the service collection
and add these two endpoints
to expose the swagger.json and Swagger UI.
Let me show that swagger.json,
which is the actual documentation
for the web API controllers.
So you can see the URL here,
localhost port number swagger
and v1 for version number swagger.json
and here you can see the information related
to all endpoints of our application.
This is the title of the application
and the default version is taken as 1.0
and this is one possible request URL
and if you make a get request,
you will get responses with 200.
The possible response could be 200
with appropriate set of cities.
The response content type can be either text by plane
or application by JSON
and text by JSON either of these
and you will get cities information
based on the schema
and what is the schema?
Components, schemas and city
and you will get to know about schemas
at the bottom of the same documentation.
Here you can see components, schemas, city
and here you can see the model class structure.
It has two properties, city ID and city name.
The city ID is a string type
and the format is UUID means GUID
and the city name is a string type.
Minimum length is one,
that means it is mandatory field.
Minimum at least one character is required.
So the schemas contains the information
related to model classes
and this is information related to endpoints
and in the same way,
if you scroll down,
this is the information related to post request.
It says that if you make a post request,
the request body should contain
either application by JSON or text by JSON
and it should contain an object of city
based on the reference of the schema.
I mean, it should include all the schema properties
that is city ID and city name.
The response could be 200 means success
and it can return the same city object
with city ID and city name.
These are all the possible response content types.
Like this, it provides documentation
for all the put, post, get and delete requests.
With appropriate parameters in the request
and response data structure.
And this is actually called as
Swagger specification or OpenAPI specification.
Based on this OpenAPI specification only,
this UI works.
See, it has displayed options like get, post, etc
based on the information from this JSON file.
That is why for this Swagger UI,
the Swagger documentation is fundamentally required.
But currently, we are going to see the same
as version number one.
We have not defined versions anywhere,
but by default, the existing code is taken as version one.
You can create multiple versions
of our Web API controllers.
We will try that in the next lecture.
Stop Play Play Play Play Play Start Start Start