Introduction
Lets say you have a WEBAPI and would like to update the documentation of that API automatically. Frameworks such as swagger and Redoc might be a good approach since they both have nuget packages available within the Visual Studio IDE for a quick and easy setup.
Setup
Right Click the WebAPI Project and click Manage Nuget Packages, to install the following packages:
- Swashbuckle.AspNetCore
- Swashbuckle.AspNetCore.Swagger
- Swashbuckle.AspNetCore.ReDoc
Swagger Configuration
In the Starup.cs file include SwagerGen in the ConfigureServices method:
public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApiDevoTo", Version = "v1" });
});
}
Include the middleware in the Configure method:
public void Configure(IApplicationBuilder app,
IWebHostEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
c.SwaggerEndpoint("/swagger/v1/swagger.json",
"WebApiDevoTo v1"));
}
Run the application and the if you created new WebAPI Project with views and controllers the weather forecast should be available as shown in the figure below.
ReDoc Configuration
Include the ReDoc middleware in the Configure method:
public void Configure(IApplicationBuilder app,
IWebHostEnvironment env)
{
app.UseReDoc(c =>
{
c.DocumentTitle = "REDOC API Documentation";
c.SpecUrl = "/swagger/v1/swagger.json";
});
}
If you run the application by default the swagger interface will appear navigate to {localhost}/api-docs to see the ReDoc interface as the figure below.
To enable ReDoc to run as default set the launch browser of your WebApi to api-docs, to do this right click the WebApi project > Properties > Debug.
Swagger X ReDoc [Free Version]
Swagger | ReDoc | |
---|---|---|
Open Source | Yes | Yes |
OpenAPI Specification | Yes | Yes |
Allows embedded HTML/CSS/JS | Yes | Yes |
Try-Me Functionality | Yes | No |
Layout with sidebars (Three panel) | No | Yes |
Conclusion
To rapidly expose your applications API frameworks such as ReDoc and Swagger is definitely a quick and practical solution. Swagger and ReDoc both offer a free and paid version and should be explored to adjust the user’s needs. Please comment on the resources you use for documenting your API.
Top comments (0)