This is part 29 of azure tutorial. In this video, we'll discuss what is swagger and
why we use it. Along the way, we'll also understand what is OpenAPI specification
and Swashbuckle. All these three terms, that is Swagger, OpenAPI specification and Swashbuckle
are extensively used especially if you're building RESTful APIs. Now, you may be wondering, why are
we talking about swagger in azure tutorial? Well, swagger is the standard for documenting apis
and in our upcoming videos we'll discuss how to deploy apis in azure. Understanding swagger
is very helpful when deploying apis in azure, hence this slight detour. If you already know what
is Swagger, then you may skip this video. Now, swagger is primarily used for documenting apis,
but why document apis? Well, whether you're building apis that are internal for your
enterprise or for public consumption, the theme is the same, they're usually used by developers
in the apps that they are building. For the other developers to be able to use your api,
it must be properly documented, otherwise how would they know what endpoints are exposed by
your api and more importantly what operations are supported on that endpoint? What parameters
should they pass and what will they get back? What authentication methods to use? So, there will be
several questions like this and you don't want to be answering these kind of questions over and over
again. So, properly documenting apis is essential if you want them to be consumed and properly used.
Now, before we understand what is swagger, let's understand what is OpenAPI specification. Lot of
people use these two terms that is OpenAPI specification and Swagger specification
interchangeably. Both of them refer to the same thing. Initially it was called
swagger specification but later renamed to OpenAPI specification. So, what is OpenAPI specification?
Well, as the name implies it's a specification. What is a specification in general? Well, it's a
set of rules that specifies how to do something. So OpenAPI specification is a set of rules that
specifies how to describe our RESTful APIs in a language agnostic way. So, irrespective of which
technology we use - Java, PHP, .NET or something else, we want our APIs to be easily consumed
by other developers in the apps that they are building. Obviously, for them to be able
to do that, they should know all the following about our API. What are the available endpoints,
for example /customers, /employees, /orders etc. Available operations at each endpoint,
again for example - GET, PUT, POST, DELETE etc. What operations are available at each of the
endpoints exposed by our API? What parameters to pass and their data types? What will the API
return and its data type, authentication methods to use etc? We want the external world or even
our internal clients to know all this information about our API without necessarily sharing
our API source code. So, there should be rules and standards around how we describe our API, so
everyone will follow the same rules and describe their APIs the same way. So OpenAPI specification
is simply a set of rules that specifies how to describe your RESTful APIs. They have rules for
describing every aspect of your RESTful service. For example, you have to follow certain rules
to specify the available endpoints at your API. Similarly, there are rules to specify
available operations at each endpoint, basically rules for everything - specifying parameters,
their data types, return values, authentication methods etc. So, simply put OpenAPI specification
is a standard and language agnostic way to describe a RESTful API. The idea is
to create a document following these rules either in JSON or YAML format that describes your entire
API - available endpoints, available operations, what parameters to pass, return value, their data
types, authentication methods, every aspect of your API basically. You can find the full
OpenAPI specification on this Github page. I'll have this link available in the description of
this video. As you can see, there are rules for describing every aspect of your APIs.
Now, take a look at this swagger website, we have a section here for describing API
parameters. Basically, this is a snippet from OpenAPI specification and has the rules on how
to describe our API parameters. So, to be able to describe the parameters that our API exposes,
we'll have to include "parameters" section and then specify a name for the parameter, its data
type, whether it is required or not and a brief description of what this parameter is for. So,
rules for describing parameters, like this there are rules in OpenAPI specification for describing
every aspect of your API. At this point, you might be wondering what's the benefit
of having a standardized specification? Well, it allows us to build tools that automate
various tasks, for example, let's say you have a Customer API,
you can point a tool at this API and ask the tool to generate the OpenAPI specification document
for your customer API. After the OpenAPI specification document is generated, you can then
point another tool at this specification document to generate the documentation for your API. Based
on this specification you can also create tools to generate server stubs and client libraries.
Now, let's take a look at a simple example. On my local machine, I have a simple API running at
this URL and when I navigate to this endpoint "/customers", I see a list of three customers
and if I want a specific customer, I pass the id of the customer in the URL. Here is the source
code. It is pretty simple and straightforward. I have a private variable here List
and within the constructor, I am initializing this private list with three customers and then,
here are the two GET methods. This GET returns the list of all customers and this GET returns
customer by id. Now, what we want to do is, we want to create OpenAPI specification document
for this customer API and we don't want to do that manually, you want to create it automatically
using tools. If you're a dotnet developer like me, there is this new get package called Swashbuckle,
let's actually right click on the project name and get to manage nuget packages. Search for
"swashbuckle.aspnetcore". As you can see, I've already installed this nuget package and if you
take a look at this dependencies window, notice, this package has a dependency on several other
packages like swagger, swagger-gen, swagger-ui. The point is, these packages help us generate not
only the OpenAPI specification document for our customer API, they also automatically generate
the documentation. Let me actually show that to you in action. Let's go to startup.cs file.
Notice, in ConfigureServices() method, I have already added the required swagger services and
if we scroll down a bit to Configure() method, notice, we are adding swagger and swagger ui to
the http request processing pipeline. Now, here's the interesting bit, with this piece of code,
if we navigate to this endpoint, we should see the OpenAPI specification document generated for this
customer API. This is the OpenAPI specification document for our Customer API. Notice,
the title is Customer API and the version is 1. We specified this information in ConfigureServices()
method while configuring swagger right here and if we scroll down a bit, notice this is the server
URL, where our API is available and here is our first path and we navigate to this endpoint, we
get list of customers and the response is 200 and if you want to take a look at the Customer object,
it is at the bottom right here. So, this is how the Customer object looks like, it has
all these properties, like customer id which is of type integer, name which is of type string
and date of birth which is of type date time and then if we scroll a bit up, we have another path
here /customers/{id} which returns us a specific customer and notice it expects a parameter here
and the name of the parameter is id, it's a required parameter and the data type is integer.
Now, here is another interesting bit, take a look at this nuget
package - Swashbuckle.Aspnetcore.SwaggerUI. If we point this nuget package at this
OpenAPI specification document of our API, it automatically generates the documentation for
our customer API and to see that documentation, navigate to this endpoint /swagger/index.html. We
have the server URL right here and it exposes two paths /customers /customers/id and if we take a
look at /customers, as you can see it doesn't have any parameters and it returns 200 okay status code
with an array of customer objects and if you want to take a look at this customer object,
the object schema is right here. It has got three properties - customer id of type integer,
name string and date of birth of type date time and we can even test our API. Notice, this "try
out" button here. Let's click it. We don't have to pass any parameters and when we click this
"Execute" button, we can see the request URL right here and the response is right here - 200
status code with an array of the three customer objects. What is OpenAPI specification? Well,
it's a set of rules that specify how you should describe your API. What is swagger? It's a set
of open source tools built around the OpenAPI specification. Swagger Codegen is one such tool
that generates server stubs and client libraries for your API. Swagger UI is another such tool
that generates interactive documentation for your API and also lets your users test the API calls
directly in the browser. Though swagger is primarily used for documenting APIs,
you can see it does more than that. Finally, what is swashbuckle? It's a nuget package and it
contains swagger tools for documenting APIs built on the microsoft.net platform. We have just seen
swashbuckle in action. I hope, you have a fair understanding of what these three terms mean
and the relationship between them. That's it in this video. Thank you for listening.