For creating OpenAPI documents in ASP.NET Core applications, the Microsoft.AspNetCore.OpenApi package provides integrated support. It offers a number of essential features to improve API documentation. It first makes it possible for OpenAPI documents to be generated during runtime, which developers may then access via a specific application endpoint. Furthermore, it incorporates "transformer" APIs, which offer the ability to alter the produced documentation as necessary. Additionally, the package facilitates the generation of many OpenAPI documents from a single application, which facilitates the effective management and organization of API specifications.
In this article, we will understand the following concepts in detail.
- Simple .Net Core Web API Project
- Understanding about Open API dcoumentation
- Swagger UI inclusion
- ReDoc Open API
- Scalar Open API
Simple .NET Core Web API Project
We will create a simple .Net core Web API project with the following steps in Visual Studio 2022.
Open Visual Studio 2022, Click on "Create new Project" then select the "ASP.NET Core Web API" option and click on "Next".
Enter the project named "OpenAPIDocDemo" in the preferred location like below and click on "Next".
The Additional Information window is shown below. for this simple demo,
we are keeping the info as-is and then clicking on the "Create" button.
After clicking on the "Create" button it shows the project like below.
We are done with a simple .Net Core Web API project.
Understanding about OpenAPI documentation
In the created project, we can observe the following referenced
package "Microsoft.AspNetCore.OpenApi" provides built-in support of
OpenAPI documentation.
The Program.cs file has the following highlighted information about OpenAPI support.
Let's run the project and append the following "openapi/v1.json" in the
browser localhost URL (Ex: localhost:7158/openapi/v1.json). We can
observe the following screen.
It indicates without doing even a small line of code changes,
The.NET9 Web API supports/generates JSON documents with the standard
format of API documentation.
Swagger UI Inclusion
Let's make very minimal changes in this demo project to include Swagger UI (our very owned habituated API documentation.
Install the following package, "Swashbuckle.AspNetCore.SwaggerUI" from Nuget.
Add the following lines of code to the Program.cs file below to the existing code line "app.MapOpenApi();"
That's it. We are done with Swagger UI inclusion in our .NET API
project. Let's run the project again with the sample URL
(https://localhost:7158/swagger/index.html). We can see the following
page.
ReDoc UI Open API Document
Let's try to include ‘ReDoc” API documentation as well in our project.
Install the following Nuget package “Swashbuckle.AspNetCore.ReDoc”
Add the following lines of code to the Program.cs file.
It's that simple..!!. We just included ReDoc API documentation in our
.NET API project. Let's run the project again with the sample URL
(https://localhost:7158/api-docs/index.html). We can see the following
page.
Scalar UI Open API Document
Let's include ‘Scalar UI” Open API documentation in our project as well.
Add the following Nuget package “Scalar.AspNetCore” to our project.
Add the following simple line of code to our Program.cs file.
So, After the inclusion of all aforesaid Open API document-related
code inclusions in the Program.cs file, the code looks like below.
Let's run our project with the sample URL (https://localhost:7158/scalar/), and the screen looks like the one below.
The Scalar API provides more GUI-friendly features with the support
of multiple programming languages of sample code if needed. These are
really helpful whenever other development teams try to include/call our
API in an easy way.
Let's try for a sample C# code for one of our existing Get methods in this sample project in the following way.
Best ASP.NET Core 8.0.11 Hosting Recommendation
One of the most important things when choosing a good ASP.NET Core 8.0.11 hosting is the feature and reliability. HostForLIFE
is the leading provider of Windows hosting and affordable ASP.NET Core, their
servers are optimized for PHP web applications. The performance and the uptime of the hosting service are excellent
and the features of the web hosting plan are even greater than what many
hosting providers ask you to pay for.
At HostForLIFE.eu, customers can also experience fast ASP.NET Core
hosting. The company invested a lot of money to ensure the best and fastest
performance of the datacenters, servers, network and other facilities. Its
datacenters are equipped with the top equipments like cooling system, fire
detection, high speed Internet connection, and so on. That is why
HostForLIFEASP.NET guarantees 99.9% uptime for ASP.NET Core. And the engineers do
regular maintenance and monitoring works to assure its Orchard hosting are
security and always up.