Professional Documents
Culture Documents
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
Lot of people use these 2 terms - 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.
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
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
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 operations at each endpoint, for example GET, PUT, POST, DELETE etc
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 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.
Install Swashbuckle.Aspnetcore
To generate documentation for your API, install Swashbuckle.Aspnetcore nuget package. The following are the steps.
1. Right-click the API project in Solution Explorer and select Manage NuGet Packages
"Swashbuckle.AspNetCore" has a dependency on the following packages which are also automatically installed.
Swashbuckle.AspNetCore.SwaggerGen: This package inspects our API routes, controllers, and models and builds the
SwaggerDocument objects.
Swashbuckle.AspNetCore.SwaggerUI: This package interprets SwaggerDocument objects and generates interactive documentation
for your API and also lets your users test the API calls directly in the browser.
After the nuget packages are installed, we need to add and configure swagger middleware. In ConfigureServices() method of
Startup.cs file, call AddSwaggerGen() method. This method adds the Swagger generator to the services collection.
services.AddDbContext<AppDbContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("DBConnection")));
services.AddScoped<IDepartmentRepository, DepartmentRepository>();
services.AddScoped<IEmployeeRepository, EmployeeRepository>();
services.AddControllers();
services.AddSwaggerGen();
In the Configure() method, enable the middleware for serving the generated JSON document and the Swagger UI
app.UseSwagger();
app.UseSwaggerUI(c =>
});
To see the generated Swagger document i.e the OpenAPI specification document, navigate to
http://localhost:<port>/swagger/v1/swagger.json
To serve the Swagger UI at the application root URL (http://localhost:<port>/), set the RoutePrefix property to an empty string:
app.UseSwaggerUI(c =>
});
The generated Swagger JSON document can be customised. This means even the API documentation can be customised, because
the API documentation is driven by the generated swagger JSON document. For example, you can use the SwaggerDoc() method
to include version, title, description, terms of service, contact person and license terms in the generated json document.
services.AddSwaggerGen(c =>
Version = "v1",
Name = "David",
Email = "david@gmail.com",
},
});
});