What is swagger?
Swagger is an incredible tool to document API. It will automatically create the documentation you need and a UI interface so you can test your controllers and endpoints.
It is amazing for public API's and if you have multiple micro services and need quick documentation, swagger is your guy. In the .net environment, one way of installing swagger is with the Swashbuckle package which we will be using today.
How to install.
First, you go to your Package Manager Console and run the following:
Install-Package Swashbuckle.AspNetCore
After the package has been installed you have to configure it in your Startup.cs file. Go to you ConfigureServices and add a swagger method called AddSwaggerGen and inside it, you will insert your documentation.
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Values Api", Version = "v1" });
});
You can control your documentation by adding a version to it. And, as long as they don't repeat, insert as many as you like.
After that, your ConfigureServices will look something like this:
The next step is to add the SwaggerUI, you will configure and add it in the Configure method in your Startup.cs file. First add the method UseSwagger, and after that, you add the method UseSwaggerUI and inside it, you add the url to access swagger, you can add as many as you like, as long as you have created the version for it in the AddSwaggerGen.
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Values Api V1");
});
After you are done, your Configure method should look like this:
Run your app and access the url your app creates and add /swagger at the end of it. Your swagger UI should show up:
That is it to install and use swagger. There are many other options to configure and use, which we won't show here. There is one last configuration I would like to talk about.
Adding a token header.
If you happen to need to install swagger in an existing application you may need a token to have your request be recognized and it is easily done with swashbuckle. You need to add it to you AddSwaggerGen method, like this:
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Values Api", Version = "v1" });
c.AddSecurityDefinition("Bearer",
new ApiKeyScheme
{
In = "header",
Name = "Authorization",
Type = "apiKey"
});
c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>> {
{ "Bearer", Enumerable.Empty<string>() },
});
});
You add a security definition and specify what exactly you need, if you ran you app again and access swagger, you will see a Authorize button in which you can add your token:
Learn more!
If you want to learn more about swagger and swashbuckle, check out these links:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore
The end.
I hope that by sharing my experience with swagger I can help you quickly install swagger and succesfully document your API's.
Any questions, comments or suggestions are greatly appreciated!
Top comments (2)
This is an awesome guide through, sure will help me a lot, Thanks!!!
Great post.
Just some side notes : if integrating this into an existing app, and catch some errors about swagger.json not found, you could haver some problemas with Routes if the verbs are not defined