Take advantage of API Analyzers and Swagger to improve the documentation of your ASP.NET Core APIs Credit: Getty Images API Analyzers, introduced with ASP.NET Core 2.2, enable you to follow a set of conventions to improve the documentation of the APIs of your ASP.NET Core applications. API Analyzers work with any controller that is decorated with the [ApiController] attribute. This article discusses how we can work with API Analyzers in ASP.NET Core 3.1. To work with the code examples provided in this article, you should have Visual Studio 2019 installed in your system. If you don’t already have a copy, you can download Visual Studio 2019 here. Create an ASP.NET Core 3.1 API project First off, let’s create an ASP.NET Core project in Visual Studio. Assuming Visual Studio 2019 is installed in your system, follow the steps outlined below to create a new ASP.NET Core project in Visual Studio. Launch the Visual Studio IDE. Click on “Create new project.” In the “Create new project” window, select “ASP.Net Core Web Application” from the list of templates displayed. Click Next. In the “Configure your new project” window, specify the name and location for the new project. Click Create. In the “Create New ASP.Net Core Web Application” window shown next, select .NET Core as the runtime and ASP.NET Core 2.2 (or later) from the drop-down list at the top. I’ll be using ASP.NET Core 3.1 here. Select “API” as the project template to create a new ASP.NET Core API application. Ensure that the check boxes “Enable Docker Support” and “Configure for HTTPS” are unchecked as we won’t be using those features here. Ensure that Authentication is set as “No Authentication” as we won’t be using authentication either. Click Create. This will create a new ASP.NET Core API project in Visual Studio. Now select the Controllers solution folder in the Solution Explorer window and click “Add -> Controller…” to create a new controller named DefaultController. We’ll use this project in the subsequent sections of this article. Install the API Analyzers NuGet package If you are using with ASP.NET Core 2.2, to work with API Analyzers in ASP.NET Core, you should install the Microsoft.AspNetCore.Mvc.Api.Analyzers package from NuGet. You can do this either via the NuGet Package Manager inside the Visual Studio 2019 IDE, or by executing the following command in the NuGet Package Manager Console: Install-Package Microsoft.AspNetCore.Mvc.Api.Analyzers Note that you do not need to install the NuGet package if you are using ASP.NET Core 3.0 or higher because the analyzers are included as part of the .NET Core 3.x SDK. Create the model and repository classes in ASP.NET Core Select the Models folder of the project we’ve just created and create a model class as shown below. public class Author { public int Id { get; set; } public string FirstName { get; set; } public string LastName { get; set; } } We’ll also need a Repository class – a simple, minimalist implementation of a repository – we’re not connecting to the database here. The AuthorRepository class is shown in the code snippet given below. public class AuthorRepository { List<Author> authors = new List<Author>() { new Author { Id = 1, FirstName = "Joydip", LastName = "Kanjilal" }, new Author { Id = 2, FirstName = "Steve", LastName = "Smith" } }; public async Task<Author> GetAuthor(int id) { var author = authors.FirstOrDefault(a => a.Id == id); return await Task.FromResult<Author>(author); } public async Task<bool> SaveAuthor(Author author) { var result = authors.Where(a => a.Id == author.Id); if(result == null) { authors.Add(author); return await Task.FromResult(true); } return await Task.FromResult(false); } } The AuthorRepository class contains two methods, namely GetAuthor and SaveAuthor. The former returns an instance of the Author class if the author is found in the collection, and the latter is used to add an instance of the Author class to the collection if the author doesn’t already exist in the collection. You may ignore the calls to Task.FromResult methods – these have been used only to satisfy the compiler. Create the controller class in ASP.NET Core Next, replace the source code of the DefaultController class with the following code. [Route("api/[controller]")] [ApiController] public class DefaultController : ControllerBase { AuthorRepository authorRepository = new AuthorRepository(); [HttpGet("{id}")] public async Task<ActionResult<Author>> Get(int id) { if (id <= 0) { return BadRequest(); } try { var author = await authorRepository.GetAuthor(id); if (author == null) return NotFound(); return Ok(author); } catch { return BadRequest(); } } [HttpPut] public async Task<ActionResult<bool>> Put([FromBody] Author author) { var result = await authorRepository.GetAuthor(author.Id); if (result == null) return NotFound(); if (author == null) { return BadRequest(); } try { var success = await authorRepository.SaveAuthor(author); if (!success) return BadRequest(); return Ok(author); } catch { return BadRequest(); } } } We’ll use this controller in the subsequent sections of this article. Install and configure Swagger in ASP.NET Core Next, you should install Swashbuckle in your project to generate Swagger documents for your ASP.NET Core API. You can do this either by installing the Swashbuckle.AspNetCore package via the NuGet Package Manager inside the Visual Studio 2019 IDE, or by executing the following command in the NuGet Package Manager Console: <span class="hljs-pscommand">Install-Package</span> Swashbuckle.AspNetCore Assuming Swashbuckle.AspNetCore package has been installed, write the following code in the ConfigureServices method of the Startup class to add Swagger to the request processing pipeline. services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "ApiAnalyzersDemo API", Version = "v1"}); }); The AddSwaggerGen extension method is used here to specify the metadata for the API documentation. You should also specify the Swagger URL and enable the Swagger UI in the Configure method of the Startup class as shown in the code snippet given below. app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1"); }); Browse the Swagger endpoint for your ASP.NET Core application So far so good. When you run the application and browse the Swagger endpoint, the documentation for the GET method should look like that in Figure 1. IDG Figure 1. Note that the Swagger documentation shows only the details of the Http Status Code 200 that is returned from the method (if it succeeds) – it doesn’t capture the other status codes that the method returns. Here is exactly where API Analyzers can help. You can take advantage of API Analyzers to fix this missing piece of information in the documentation. If you’re using ASP.NET Core 2.2, when you compile the code, you’ll see the warnings as shown in Figure 2. IDG Figure 2. Select any of the warnings and then press the “Ctrl” and “.” keys together to see the potential fixes. You can see that the recommended fix is to add the ProducesResponseType attribute as shown in Figure 3. IDG Figure 3. Since we’re using ASP.NET Core 3.1 here, you can add the following attributes at the top of your method or controller class in order to document all of the HTTP status codes being used in the action method, i.e., 200, 400, and 404. [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status404NotFound)] [ProducesDefaultResponseType] Complete ASP.NET Core API Analyzers example The following code listing shows the complete code of the DefaultController class for your reference. [Route("api/[controller]")] [ApiController] [ApiConventionType(typeof(DefaultApiConventions))] public class DefaultController : ControllerBase { AuthorRepository authorRepository = new AuthorRepository(); [HttpGet("{id}")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status404NotFound)] public async Task<ActionResult<Author>> Get(int id) { if (id <= 0) { return BadRequest(); } try { var author = await authorRepository.GetAuthor(id); if (author == null) return NotFound(); return Ok(author); } catch { return BadRequest(); } } [HttpPut] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status404NotFound)] public async Task<ActionResult<bool>> Put([FromBody] Author author) { var result = await authorRepository.GetAuthor(author.Id); if (result == null) return NotFound(); if (author == null) { return BadRequest(); } try { var success = await authorRepository.SaveAuthor(author); if (!success) return BadRequest(); return Ok(author); } catch { return BadRequest(); } } } Now run the application again and browse to the Swagger URL. Figure 4 shows what the output should look like. IDG Figure 4. API Analyzers is a useful addition to ASP.NET Core. As we’ve seen, you can take advantage of API Analyzers and Swashbuckle, an open source project for generating Swagger documents, to generate better API documentation. Because API Analyzers can document a status code that isn’t returned from an action method, it makes documenting your APIs faster and easier. For API documentation we’ve used Swashbuckle, an open source project for generating Swagger documents. You can learn more about Swashbuckle from my previous article here. How to do more in ASP.NET Core: How to use route data tokens in ASP.NET Core How to use API versioning in ASP.NET Core How to use Data Transfer Objects in ASP.NET Core 3.1 How to handle 404 errors in ASP.NET Core MVC How to use dependency injection in action filters in ASP.NET Core 3.1 How to use the options pattern in ASP.NET Core How to use endpoint routing in ASP.NET Core 3.0 MVC How to export data to Excel in ASP.NET Core 3.0 How to use LoggerMessage in ASP.NET Core 3.0 How to send emails in ASP.NET Core How to log data to SQL Server in ASP.NET Core How to schedule jobs using Quartz.NET in ASP.NET Core How to return data from ASP.NET Core Web API How to format response data in ASP.NET Core How to consume an ASP.NET Core Web API using RestSharp How to perform async operations using Dapper How to use feature flags in ASP.NET Core How to use the FromServices attribute in ASP.NET Core How to work with cookies in ASP.NET Core How to work with static files in ASP.NET Core How to use URL Rewriting Middleware in ASP.NET Core How to implement rate limiting in ASP.NET Core How to use Azure Application Insights in ASP.NET Core Using advanced NLog features in ASP.NET Core How to handle errors in ASP.NET Web API How to implement global exception handling in ASP.NET Core MVC How to handle null values in ASP.NET Core MVC Advanced versioning in ASP.NET Core Web API How to work with worker services in ASP.NET Core How to use the Data Protection API in ASP.NET Core How to use conditional middleware in ASP.NET Core How to work with session state in ASP.NET Core How to write efficient controllers in ASP.NET Core Related content how-to How to use FastEndpoints in ASP.NET Core Take advantage of the free open-source FastEndpoints library to build fast and lean APIs in your ASP.NET Core applications. By Joydip Kanjilal Jul 11, 2024 7 mins Microsoft .NET C# Development Libraries and Frameworks how-to How to use Refit to consume APIs in ASP.NET Core Take advantage of Refit REST library to simplify API consumption and make your code cleaner, more efficient, and easier to maintain. By Joydip Kanjilal Jul 04, 2024 10 mins C# Microsoft .NET Software Deployment how-to When to use an abstract class vs. interface in C# Understanding the differences between an abstract class and interface is key to designing loosely coupled and extensible applications. By Joydip Kanjilal Jun 20, 2024 10 mins Small and Medium Business Microsoft .NET C# how-to 6 security best practices for ASP.NET Core Learn the best practices and built-in safeguards for preventing attacks and protecting sensitive data in your ASP.NET Core web applications. By Joydip Kanjilal Jun 07, 2024 6 mins C# Microsoft .NET Web Development Resources Videos