Are you looking for web api tutorials for beginners? Are you new to build an asp.net core web api and looking for examples? Do you know how to generate the web api documentation? If you’re finding the answers, this article guides you to develop an asp.net core web api. Furthermore, you will learn to set up the web api documentation using Swashbuckle.

The asp.net core is an open-source web application framework in .NET like Express for Node.js and Django for Python. It helps you to develop the asp.net core web api following the RESTful pattern. On the other hand, the users may need the web api documentation before using it. You’ll use Swashbuckle – a Swagger/OpenAPI implementation for .NET and generates the documentation to consume.

I’ll start with an asp.net core web api with a basic CRUD operation. The backend database is SQL Express and it uses EF Core, an ORM tool to connect the database from the web api. Additionally, I’ll configure the Swashbuckle for the web api documentation and test the asp.net core web api in the browser. Let’s follow the table of contents below

• Download Visual Studio Code and related tools
• Create a solution containing a web api project
• Prepare the web api for database connectivity
• Create the model and data source context
• Configure data source context and database initializer
• Create a web api controller
• Configure Swashbuckle for web api documentation
• Run and test the web api

Download Visual Studio Code and related tools

Install .NET 5.0 SDK is pretty straightforward. You need SDK (which includes runtime) for the development purpose. You’ll use Visual Studio Code (VS Code) which is a lightweight and powerful source code editor. It runs on your desktop and is available for Windows, Mac OS and Linux. It supports most of the languages using extensions. You can download VS Code from their site. The SQL Express is the free version of SQL Server and ideal for development purposes. You can also download SQL Express from the SQL Server site. Once the tools are installed, you can open VS Code and install the following two extensions from the marketplace

• C# for visual studio code – It helps to write code in C#
• Nuget package manager – It helps to manage NuGet packages

Create a solution containing an asp.net core web api project

Once the development tools are ready to use, you will set up the solution containing an asp.net core web api project. Please follow the steps below in order

• Create a folder named eKart and open the folder in VS Code
• Open VS Code and click on terminal [Ctrl + `]
• Fire up the below commands in the order mentioned below

Prepare the asp.net core web api for database connectivity

The objective is to build the asp.net core web api with the database operations. Nevertheless, I’ll use EF Core – an ORM tool to connect the SQL database and perform the CRUD operation. It requires the following NuGet package to add to the asp.net core web api project.

Perhaps the easiest way to add packages in visual studio code is to use the shortcut key [Ctrl + Shift + P] to open the command palette and type nuget. The following dialog appears and you can follow on-screen guidance to add the above packages. Once added, the package information is added to the csproj file.

Create the model and data source context

I will begin with a POCO (Plain Old CLR Object) class Product to map the Product entity.

Additionally, a data source context is required to have two-way communication between the Product entity and the data source (SQL database) using EF Core. Apparently, I can use different data source contexts like SQL database context, in-memory data source context etc. This article uses SQL data source context i.e. DbContext.

Configure data source context and database initializer

EF Core supports a code-first approach to generate database objects of the business entity i.e. Product POCO class. It creates the database table directly from the POCO class. The data source context performs all the magic behind the scene. To create the table in the database, the web api has to connect to the database. Let’s add the data source context and pass the database connection string. It is a recommended practice to use user secrets while defining and storing sensitive information like database name, user name, password, connection string etc. It also prevents sensitive information to store in an open code sharing platform like GitHub. I’ll use user secrets to store the connection string. Please check here to know about it.

After connecting to the database, the data source context creates the tables etc. Additionally, the context can initialize the tables with the data if required. The data initialization of the EF Core is a useful feature to prepare the master data in the database tables along with the table creation.

The asp.net core web api first configures the data context and then call the database initializer to initialize the data in the table.

Create an asp.net core web api controller

The controller is the main entry point of the asp.net core web api. It contains the endpoints to represent the HTTP verbs like GET, POST, PUT, and DELETE performing basic CRUD operations. Additionally, it uses data source context i.e. eKartContext to communicate with the database. The data source context is already injected in the above step using asp.net core dependency injection framework.

Configure Swagger to test the asp.net core web api

Once you run the web api project, you cannot test it using a browser (certain browsers doesn’t support it). Either you have to use Fiddler/Postman/other REST api tools to call the api endpoints and test them. The recommended way is to list down the available api endpoints using Swashbuckle – a .NET implementation of Swagger/OpenAPI. Swashbuckle is a useful tool for generating web api documentation. To use Swashbuckle, you need to add the following NuGet package

Configure the Swashbuckle in asp.net core web api is easy to do. You’ll add the swagger generator, swagger middleware and swagger UI to enable the swagger endpoint with the web api documentation.

Run the asp.net core web api

Finally, You are ready to run and test the asp.net core web api project on a local machine. You can type the following commands to run it

The asp.net core web api is accessible to https://localhost:5001/swagger/index.html. It’s reading the connection information of the database from the user secrets stored locally and connecting to the database. The sample content of the user secret file is shown below.

This tutorial helps you to build an asp.net core web api following the RESTful pattern, reading, writing the data to the SQL database and provide the web api documentation using Swashbuckle. It uses the local server to run. The asp.net core web api code is located in the Github repository eKart. As a next step, I encourage you to check the tutorial How to deploy Azure app service using Azure pipeline to deploy the web api to Azure app service. I hope you find this article useful. Please share your feedback below in the comments section and I’ll respond to them as early as possible.