Searching for a better visualisation for my APIs, I was looking for an alternative to Swagger. WebApiDocumentator is a quick and easy way to create an interface to document a WebAPI built in .NET Core. It creates a user-friendly interface and has options for endpoint testing.
I used Swagger for a long time. Working with programmers who aren’t from the .NET Core world. Also, I realized that Swagger isn’t always very clear when it comes to documenting APIs.
When using a well-documented public or private API, you realize the shortcomings of Swagger. It really leaves a lot to be desired.
For an external programmer, knowing exactly how to make requests can be confusing with Swagger. This is especially true because it orders endpoints based on files. It does not order them by generated paths.
WebApiDocumentator
So, I found this package created by Sergi Ortiz Gomez that it is quite cool. The source code of this package is available on GitHub. The features of this NuGet package are:
- Automatic documentation using XML metadata from C# code
- Show endpoints tree structure
- HTML interface
- Test endpoints
Installation
Install the NuGet package via the package manager:
dotnet add package WebApiDocumentator
Or by using the NuGet CLI
nuget install WebApiDocumentator
Quick Start
Step 1: Add WebApiDocumentator to Your API
In your Program.cs, you will need to add the middleware to your service collection and configure the options.
1.1 Configure Options
You can customize the url for the page and add basic data via DocumentatorOptions.
In appsettings json using IOptions<DocumentatorOptions> file like:
"DocumentatorOptions": {
"ApiName": "Your api name",
"Version": "Your version, it's a string",
"Description": "Full descripcion about your API",
"DocsBaseUrl": "documentation path, defatul it's [api root]/WebApiDocumentator"
}
Or directly like:
public void ConfigureServices(IServiceCollection services)
{
services.AddWebApiDocumentator(options =>
{
options.ApiName = "Test Api";
options.Version = "v1";
options.Description = "The best API in the world!";
options.DocsBaseUrl = "docs/api"
});
}
//minimal api
builder.Services.AddWebApiDocumentator();
//Or also can do to read the appsettings.json
/*
builder.Services.AddWebApiDocumentator(
options => builder.Configuration.GetSection(SmartCacheOptions.SectionKey).Bind(options)
);
*/
1.2 Add the user interface
In your Configure method, add the middleware to the pipeline using UseWebApiDocumentator():
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// Add other middlewares like routing, authentication, etc.
app.UseWebApiDocumentator();
}
//minimal api
app.UseWebApiDocumentator();
Step 2: Interface HTML
To access to the interface you can use the default URL
[your api url]/WebApiDocumentator
Or if you personalise the URL then use your own URL
[your api url]/docs/api
Remind: You can always use a default WebApiDocumentator page.
2.1 Home page
- Show the name, version and description from your options.
- Show the schema of your API
- Right side bar to search and select endpoints
2.2 Selected endpoint
- Show documentation information
- Show parameters type and from where
- Show testing tab
Example of the output
