This is a walk-through article by one of ClinkIT Solutions’ software developers providing the steps on how to use Swagger for .NET Core API Documentation Representation.
Being a back-end developer means setting up the backbone, making a high-level architectural plan, dealing with the server side of the application to make different platform types function as intended. There’s more about the role that I didn’t mention, and one of them is creating documentation which we, developers, commonly dislike. Maintaining them as part of your evolving application takes a lot of time that could have been used for working on more features.
Understanding a Web API’s various methods can be challenging for a developer. Swagger, also known as OpenAPI, can generate useful documentation and help pages for Web APIs. This addresses a lot of problems and saves us time. In this article, we will be setting up and implement Swashbuckle.AspNetCore which is an open source project for generating Swagger documents for ASP.NET Core Web APIs.
Let’s Begin!
What we have below is a simple To-do API that is using ASP.NET Core 3.1.
Our To-do Controller that has,
get all To-dos,
get a To-do,
update a To-do,
and lastly, delete a To-do.
Simply put, the codes above are the following endpoints or API calls that will be represented in our Swagger UI later:
Method
Route
Description
Parameter
Request Body
Response Body
GET/api/todos Get All to-do items NoneNoneList of to-do items GET/api/todos/{id}Get an item by IdId of an itemTo-do itemTo-do itemPOST
/api/todos
Add a new itemNoneNoneTo-do item
PUT
/api/todos/{id}Update an existing itemId of an itemTo-do itemNoneDELETE/api/todos/{id}Delete an itemId of an itemNoneNone
Installation
Let’s now install Swashbuckle.AspNetCore into our API project with NuGet Package Manager.
Implementation
Once installed, we need to register Swagger middleware in our Services. The highlighted lines of code below register Swagger generator and defines Swagger document.
app.UseSwagger() enables middleware to serve generated Swagger as a JSON endpoint and app.UseSwaggerUI() enables middleware to serve Swagger UI specifying the JSON endpoint.
Now that everything is in place. Let’s launch the app and we should now see the beautiful Swagger UI by navigating to http://localhost:/swagger.
As you can see, Swagger UI represented the following Endpoints that we’ve listed in the table earlier together with their defined Parameter, Request Body, and Response.
OpenAPI recognized a Controller class with [ApiController] attribute together with its valid Route that doesn’t have a conflict with other controllers. Same goes for Actions and Routes inside the Controllers, everything should be defined clearly, or else Swagger UI will not load correctly.
We can also use Swagger UI to test out API Calls by clicking the “Try it out” button and filling in predefined Parameters and Request Body. Check the Response right after executing it.
Now, we won’t have to spend so much time on maintaining documentation, since it is already reflected in the API definitions as we add new features. We can also use it as a well-presented documentation that other developers, project managers, and clients can play around with.
Get the latest insights on developer best practices, technologies and solutions for businesses here. Need help with application development or other development services? Schedule a free consultation with us.
