Creating API Documentation with Swagger: A Beginner’s Tutorial

Swagger is the standard approach to documenting the Standard APIs. Swagger is an open-source set of rules, determinations and instruments for creating and portraying RESTful APIs.
The capacity of APIs to portray their own design is the foundation of all amazingness in Swagger. It is fundamentally utilized for documenting API.
Swagger is basically an asset posting of your API. It incorporates data like:

  • What are all the operations that your API supports?
  • What are your API’s parameters and what does it return?
  • Does your API need some authorization?

History of Swagger

The Swagger API project was done in 2011 by Tony Tam. The framework was intended to ease API robotization and its documentation. The task was then made open source where it built up some forward momentum with organizations and developers.
In 2015, the organization that kept up with Swagger, SmartBear Software, helped found the OpenAPI drive, an association that is supported by the Linux Foundation. After a year, Swagger was renamed to the OpenAPI Specification and was moved to another GitHub storehouse.

Swagger is presently the biggest framework for planning APIs with a typical language.

Benefits of Swagger

  • It has a well-disposed UI that guides the diagram for APIs.
  • Produces intelligent, effectively testable documentation.
  • Design is adequate in JSON and YAML to empower simpler alters.

Components of Swagger

Swagger provides a variety of open source tools for APIs, including:

  • Swagger Editor-This empowers developers to compose documentation for, plan and depict new APIs as well as alter existing ones. The program-based manager outwardly delivers OpenAPI determinations, handles mistakes and gives ongoing criticism.
  • Swagger Codegen-This empowers developers to create client library code and SDKs for various stages.
  • Swagger User Interface-This is a completely adaptable instrument that assists engineers with creating documentation for different stages. It tends to be facilitated in any climate.
  • Swagger Inspector-This is a trying device for API documentation. APIs can be handily approved unbounded and results are naturally saved and gotten to in the cloud.

Swagger UI

Strut UI offers a web-based UI that gives data about the help, utilizing the produced OpenAPI determination. Both Swashbuckle and NSwag incorporate an implanted rendition of Swagger UI, so it very well may be facilitated in your ASP.NET Core application utilizing a middleware enrollment call.

Swagger with .NET Core

In .NET 6 Web API project, Swagger is added by default. When you run your Web API project it redirects you to the Swagger Index page.

To enable Swagger API definition, we need to add Swashbuckle.AspNetCore from nuget package manager.

Next, in Program.cs file and add the Swagger generator to the service collection.

builder.Services.AddSwaggerGen();

And in Program.cs file before the HttpRedirection pipeline to enable the middleware.

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Now the query is, why it is straightforwardly going to the Swagger UI page? All things considered, it is going there because “launchUrl”: “swagger” is set in the launchsettings.json file.

Hope this article is useful to you. Follow SharePointCafe.Net for more details.

Leave a Comment

RSS
YouTube
YouTube
Instagram