This post is going to be very similar to a post from last December which can be found here. A lot has changed since then and this post is going to add Swagger to an existing ASP.NET Core application using Swashbuckle much like the one from last year. The starting point of the code can be found here.
What is Swagger?
Swagger is a specification used to document an API. As I am sure we all know API documentation tends to get out of date fast and a lot of times is a low priority.  Swagger aims to help solve that problem using a format that is both human and machine readable which can be maintained in either JSON or YAML. The documentation can be auto generated using a tool like Swashbuckle which provides away to keep your consumers up to date. Check out this post by the Swagger team for the full introduction.
What is Swashbuckle?
Swashbuckle provides auto generation of Swagger 2.0, a UI, etc. The project takes all the pain out of getting going with Swagger as well as providing tools and hooks for using and customizing Swagger related items. The full description can be found here.
Adding Swashbuckle
Using your favorite method of NuGet interaction, add the Swashbuckle.AspNetCore NuGet package to your project. Personally, I have gotten where I edit the csproj file to add new packages. If that is your style you would need to add the following package reference.
<PackageReference Include="Swashbuckle.AspNetCore" Version="1.0.0" />
This one package provides all the functionality we will need.
Wiring up Swashbuckle
Now that the Swashbuckle package is installed, there are a few changes that are needed in the Startup class to get everything wired up. First, in the ConfigureServices function, the Swagger generator needs to be added to DI.
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Contacts API", Version = "v1"});
});
AddSwaggerGen allows for configuration of options, but here we are just setting a name and a minimal amount of information.
In the Configure function Swagger needs to be added to the request pipeline in order to expose the Swagger generated data. I placed this after UseMvc.
app.UseSwagger();
At this point, the Swagger generated JSON would be available at {yourBaseUrl}/swagger/v1/swagger.json. To take a step further let’s expose the UI that comes with Swashbuckle. Add the following just below app.UseSwagger().
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Contacts API V1");
});
Now a UI based on your API is available at {yourBaseUrl}/swagger with zero extra work on your part. The following is the UI for the post contact route in the example project.
As you can see the UI provides a great view of your API as well as ways to try it out and the potential responses that should be expected from a call.
Controller Considerations
All of this wonderful functionality doesn’t come for free of course. In order for Swashbuckle to pick up your routes, your controller will need to use attribute based routing instead of depending on convention based routing.
In order for Swashbuckle to know the return types and of your controller actions may need to have some attributes added. This won’t be required if your action return a specific type, but if you are returning an IActionResult you should attribute your action with all the ProducesResponseType you need to cover the results of your action. For example, the following is the action definition for the Post in the screen shot above.
[HttpPost] [ProducesResponseType(typeof(Contact), 200)] [ProducesResponseType(typeof(IDictionary<string, string>), 400)] [ProducesResponseType(typeof(void), 400)] [ProducesResponseType(typeof(void), 404)] [ProducesResponseType(typeof(void), 409)] public async Task<IActionResult> PostContact([FromBody] Contact contact)
Wrapping up
Swashbuckle makes it easy to add Swagger to a project. I feel that it also provides a huge value for anyone trying to consume an API. It is of course not a magic bullet and communication with your API consumers about API changes will still be critical.
Microsoft’s docs have a great walk through which can be found here. It does more in-depth on customizing your setup and as far as modifying the look of the UI. I also recommend checking out the GitHub page for the project which can be found here.
The finished code can be found here.
Also published on Medium.
Bro, has anyone written out a template or example of a very simple .net core 2 Web api controller with GET, GET/id, PUT, POST, DELETE methods and all the decorations they would normally need? For example create a basic project in VS, then Scaffold a web api controller with Entity Framework entities included. Then mark up that resulting file with [ProducesContentType] attributes so Swashbuckle works correctly. Seen that anywhere?
Sorry, I don’t know of an example that covers all that. If you do find one please come back and share a link!
Nice. I have written step by step guide for using Swagger with .Net Core 2.0 here: https://neelbhatt40.wordpress.com/2017/12/11/enable-swagger-in-your-net-core-2-0-application-step-by-step-guide/
how to restrict access to swagger , we dont want others see our api methods. what i need is to ask for username and password to access swagger page
I have not tried this myself, but check out this issue it talks about how to handle your situation.
Are there plans to support YAML format? JSON seems to be the only supported format and default option at this time. What about the ability to generate a spec at an endpoint that doesn’t begin with /swagger/ ?
I’m not sure. I would recommend that you ask in the project’s github.
Thanks for this post.I working on my project I’ve been using the postman before and then i use swagger.
I want to definate default property value on Request Model for request on swagger.
Ex :
public class LoginRequest
{
[Required(ErrorMessage = “Email required”)]
[DefaultValue(“Test”)]
public string email { get; set; }
[Required(ErrorMessage = “Parola Zorunlu Alan”)]
[DefaultValue(“Test”)]
public string password { get; set; }
}
But DefaultValue attribute is not set in Swagger UI. :(
Ex :
{
“email”: “string”,
“password”: “string”
}
Actually, I was hoping it would be
{
“email”: “Test”,
“password”: “Test”
}
How, Can i made it ?
Sorry, Bahadir I’m not sure how to accomplish what you are looking to do. If you find an answer please post it back here and if I or another reader finds an answer we will do the same.
I found it but i don’t share link in comment :(.
If you don’t mind email it to me and I will add it. elanderson at Gmail.
Of course actually i was wrong write. Actually i can’t share link in comment.
I send to you.
Here are the likes from Bahadir. Thanks for sharing!
1) https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/test/WebSites/Basic/Swagger/ExamplesSchemaFilter.cs
2) https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/1ba00c70a0529341fba0959e656d36a29ccae1b2/test/WebSites/Basic/Startup.cs#L55
3) https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/07fbdeb187f558dad7e0e4afb9512ff5ccf98d6e/src/Swashbuckle.AspNetCore.SwaggerGen/Generator/SchemaExtensions.cs#L15-L23
How do you generate the client for a consuming application/library written in .NET Cor/Standard?
I have always done the client side manually, but I wouldn’t be surprised if there is a tool that would do it for you.
Thank you so much for the detailed one.
Your welcome!
Pingback: Swagger/OpenAPI with NSwag and ASP.NET Core 3 – Eric L. Anderson