ASP.NET Core API Documentation Using Swashbuckle.AspNetCore And .NET CLI

In this article, we will discuss how we can create documentation for API projects.

Swashbuckle.AspNetCore is a swagger tool for API’s built with ASP.NET Core. We shall create an API project and add the documentation using Swashbuckle.AspNetCore project.

For this, let's create an API project with the help of dotnet CLI. (To start building .NET apps you just need to download and install the .NET SDK (Software Development Kit). )

Create an API project under a new folder (example, APIDocumentation) using the following command in the command prompt:

dotnet new api

ASP.NET Core API Documentation Using Swashbuckle.AspNetCore And .NET CLI

Once we have run the commands, our scaffolds get crated with a sample controller called ValueController.

namespace APIDocumentation.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
// GET api/values
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "value1", "value2" };
}
// GET api/values/5
[HttpGet("{id}")]
public ActionResult<string> Get(int id)
{
return "value";
}
// POST api/values
[HttpPost]
public void Post([FromBody] string value)
{
}
// PUT api/values/5
[HttpPut("{id}")]
public void Put(int id, [FromBody] string value)
{
}
// DELETE api/values/5
[HttpDelete("{id}")]
public void Delete(int id)
{
}
}
}

Install the standard package of Swashbuckle.AspNetCore into your ASP.NET Core application.

dotnet add package Swashbuckle.AspNetCore

Restore package dependencies using the following command

dotnet restore

Once we have run the restore command, the CLI will install all the project dependencies under our directory.

In the next step, we must register our swagger generator in the configuration service. For that, we need to add the following code in startup.cs under ConfigureServices and add using Swashbuckle.AspNetCore.Swagger; in directives.

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

By default, your API actions and non-route parameters are decorated with explicit "Http" and "From" bindings. If it’s not available, we must add those bindings in our API.

Example

[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "value1", "value2" };
}

Next, in the Configure method, we must insert middleware to expose the generated Swagger as JSON endpoint(s) like below,

app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

We have completed all the steps that we need to set up a basic API documentation of swagger. Now we are able to run the application and visit the documentation.

We can run the application using the following CLI command

dotnet run

The application will start running and the endpoint information will get displayed in the command prompt.

We shall visit the documentation page using the link,

<<endpoint>>/swagger

Example

Here, our application is hosted in localhost:5001. So we can visit https://localhost:5001/swagger to visit our API documentation.

Based on our Controller and Http methods, our documentation has been generated. We can extend documentation further based on our needs.

2 Comments

Join the conversation! Your thoughts help the community grow.

mohammad8y ago
Can we automate the documentation? like as soon as i add a controller the documentation needs to get updated automatically?
- Pandiyan8y ago
  Yes, if you add the new controller with HTTP verbs convention. example [HttpGet] it will automatically update the existing documentation. you don't have to update documentation each time.