This is Part 30 of Azure tutorial. In this video we will discuss, how to use Swagger
in ASP.NET Core Web API and automatically generate API documentation. In our upcoming
videos, we will discuss how to deploy this web API in azure. Now, take a look at this
solution - EmployeeManagement. We have got two projects within this solution - EmployeeManagement.Api
and EmployeeManagement.Models and if we take a look at this API project, we have got two
controllers - Departments and Employees. If we take a look at this EmployeesController,
we've got all the CRUD operations that is Create, Read, Update and Delete, including
Search. This is a RESTful service that we have built from scratch in our Blazor course.
So, if you're new to building RESTful services using ASP.NET core, I strongly recommend to
check out our Blaozr tutorial for beginners course. In this course, we've covered building
this Employee Management API from scratch. So, in part 10 of this video series, we discussed
what are RESTful APIs and covered all the CRUD operations including search in part 20.
So, if you want to follow along and build this Employee Management API from scratch,
then please watch videos from part 10 to part 20. When we navigate to this endpoint, api/employees,
we see the list of all employees and we get this list from a SQL server database and if
we want a specific employee we pass the id of the employee in the URL. Similarly, if
we want the list of all departments, we go to this end point api/departments. Again,
if you want a specific department, simply pass the id of the department in the URL.
At the moment, this API does not have any documentation whatsoever. So, if we navigate
to this endpoint /swagger, we get a 404. Now, let's say we don't want to share our API code,
but we want the other developers to be able to consume and use our API in the apps that
they are building, but then without documentation for them to be able to consume our API, they
will have several questions like what endpoints are available at your API and what operations
are supported at each of those endpoints - GET, PUT, POST, DELETE, SEARCH etc, what parameters
should I pass and what will I get back. We will have to answer several questions like
this over and over again. It's boring and not efficient. On the other hand, if we have
swagger documentation for our API, we simply ask the developers to navigate to our server
URL/swagger and then they will have answers for all their questions. They can even point
some automated tools at our swagger API documentation and then generate the client libraries automatically,
they don't even have to write the code manually themselves. Just imagine how efficient it
can be, both for us, as well as the other developers who are consuming our API in the
apps that they are building. Now, we discussed OpenApi specification, Swagger, Swashbuckle
and the relationship between them in detail in our previous video. So, let's quickly recap,
OpenApi is a specification, that is, it's a set of rules that specifies how to describe
an API. Swagger is a set of open source tools built around the OpenApi specification. Swashbuckle
is a nuget package and it contains swagger tools for documenting APIs that are built
on Microsoft .Net platform. Now, if we want swagger documentation to be generated for
our Employee Management API, all we need to do is, install this nuget package - Swashbuckle.Aspnetcore
and configure it. In visual studio, in the solution explorer, right click on your API
project and then select this option - Manage nuget packages. Make sure you're on the Browse
tab and search for Swashbuckle.Aspnetcore. Here is that package. Let's select it and
take a look at this dependencies, it has dependency on several other packages. These dependencies
will also be automatically installed, so click the Install button.
There we go, installation complete. This main package Swashbuckle.aspnetcore has a dependency
on the following three nuget packages SwaggerGen, Swagger and SwaggerUI. The first package SwaggerGen
inspects our API code, that is our API routes, controllers and models and then builds the
swagger document objects automatically. The second package Swagger exposes swagger document
objects as JSON endpoints and the final package that is SwaggerUI interprets swagger document
objects and generates interactive documentation for our API and also lets our users test the
API calls directly in the browser. Our next step is to configure swagger and we do that
in startup.cs file of our API project. In ConfigureServices() method, on this incoming
parameter IServiceCollection
call AddSwaggerGen() method, notice the name of the method, SwaggerGen, it stands for swagger
generator. As the name implies, this method adds swagger generator to the services collection.
Next, in the Configure() method, we need to add swagger middleware to the http processing
pipeline. So on this incoming parameter IApplicationBuilder, we call UseSwagger(), this middleware serves
the generated swagger document as a json endpoint. We'll see that in action in just a bit. We
need to add another piece of middleware and that is SwaggerUI. This piece of middleware
looks at this endpoint /swagger/v1/swagger.json, remember it is this json document that contains
the OpenApi specification document for this Employee Management API, so the SwaggerUI
looks at this json document and automatically generate the documentation for our Employee
Management API. So, to configure swagger in an asp.net core web API project, all we need
is, these three lines of code - AddSwaggerGen(), this adds swagger generator to the services
collection and then these two pieces of middleware. With these three lines of code, let's run
our API project. There we go, we have our API up and running. Now, if we navigate to
this URL - swagger/v1/swagger.json, we see the OpenApi specification document for our
Employee Management API and remember it is this document that drives the documentation
for our API and to see the documentation in action, just navigate to this URL - /swagger.
There we go, as you can see this employee management API supports two endpoints - Departments
and Employees. This endpoint, department, supports two GET operations and this end point
Employees, supports GET, POST, PUT and DELETE. We also have SEARCH here as a GET operation
and if we scroll down a bit, we have the schema for all the objects - Department, Employee
and Gender and if you take a look at the Department object, it has two properties - DepartmentId
and DepartmentName along with their data types and we can also try out these API calls right
from within the browser. For example, let's try this endpoint GET employee by id and to
try it, click this button, Try it out and notice, id is a required parameter. To be
able to get employee by id, you need to specify the id of the employee and then click the
"Execute" button. We have the request URL right here. Notice, the id of the employee
is passed in the URL and we have the response.
Now, remember, when we navigate to this URL - swagger/v1/swagger.json, we see the OpenApi
specification document for our employee management API. This generated swagger json document
can be customized, this means even the API documentation can be customized, because the
API documentation is driven by this generated swagger json document. For example, in ConfigureServices()
method, let me replace this line with another piece of code. It's still calling, AddSwaggerGen()
which obviously adds swagger generator to the services collection. In addition, we're
also calling SwaggerDoc() method and this method is used to add version, title, description,
terms of service, contact person and license terms to the generated swagger document and
to fix these compilation errors, we need to bring in a namespace and the name space that
we need is Microsoft.OpenApi.Models
Notice, now in the generated OpenApi specification document, we have title, description, terms
of service etc and if we navigate to the swagger documentation, we see the same right here.
So, the point that I'm trying to make is along with the SwaggerDoc() method that we have
just seen, we can also use XML comments and data annotations to control the generated
swagger json document and the API documentation. Now, how to use xml comments and data annotations
for customization? Well, that is beyond the scope of this video, maybe we'll cover them
in the future in a separate course. In our next video, we'll discuss how to deploy this
employee management API in azure. That's it in this video. Thank you for listening.