What is Swagger

In this video we will discuss what is swagger and why we use it. Along the way, we will also understand what is OpenAPI specification and Swashbuckle.

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 will discuss how to deploy APIs in azure. Understanding swagger is helpful when deploying APIs in azure, hence the slight detour. If you already know, what is Swagger, you may skip this video.

Why document APIs

Swagger is primarily used for documenting APIs, but why document APIs? Well, whether you are building APIs that are internal for your enterprise or for public consumption, the theme is the same, they are 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 at each available enpoint
• What parameters to pass and 
• What will they get back (return value)
• What authentication methods to use

You don't want to be answering these kind questions over and over again. So, properly documenting APIs is essential, if you want them to be consumed and properly used. 

We will discuss, what is Swagger in just a bit, but before that, let's understand OpenAPI specification.

OpenAPI Specification v/s Swagger Specification

Lot of people use these 2 terms - OpenAPI specification and Swagger specification interchangeably. Both of them refer to the samething. Initially it was called swagger specification but later renamed to OpenAPI specification. 

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.

Irrespective of which technology we use (Java, PHP, dot net or something else), we want our APIs to be easily consumed by other developers in the apps that they are building. Obvisously for them to be able to do that, they should know all the following.

• What are the available endpoints, for example /customers, /employees, /orders etc
• Available operations at each endpoint, for example GET, PUT, POST, DELETE etc
• What parameters to pass and their data types
• What will the API return and the 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, 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, for example /customers, /employees, /orders etc
• Available operations at each endpoint, for example GET, PUT, POST, DELETE etc
• What parameters to pass and their data types
• What will the API return and the data type
• Authentication methods to use etc.

You can find the full OpenAPI specification at the following link
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

Benefit of a standardised specification

Well, it allows us to build tools that automate various tasks.

• For example, let's say you have a CustomerAPI. You can point a tool at this API and ask the tool to generate the OpenAPI specification document for your CustomerAPI.
• 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 genereate server stubs and client libraries.

Swagger vs OpenAPI vs Swashbuckle

What is OpenAPI

• OpenAPI is a specification i.e it is a set of rules that specifies how you should describe your API.

What is Swagger

• Swagger is 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 in over 40 languages.
• 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, it does more than that.

What is Swashbuckle

• Swashbuckle is a nuget package and it contains Swagger tools for documenting APIs built on Microsoft.NET.