Swagger for WebAPIs
When we buy a product, the catalog of the product plays a key role in understanding the features and how to use them effectively. Similarly, in the software world, the documentation of the functioning code is as important as writing the code itself. Terrible documentation or no documentation results in wastage of human efforts in the long run.
In the modern web development sphere, APIs are playing a critical role in the data transfer. But, there is no industry standard for designing and documenting the APIs. To understand and make use of the API, they have to be accessible in a user-friendly manner. They should also have clear documentation on the functionality of the endpoints of the API, which makes the developers and testers to understand it more easily. Thankfully, there is a specification called Swagger that helps in accessing and understanding the APIs. This post will answer questions like what is Swagger, why to use it, and also look at a practical implementation of Swagger.
Table of contents
- What is Swagger?
- Why use Swagger?
- Swagger tools for APIs
- Practical implementation of Swagger
- Wrapping up
What is Swagger?
Swagger, also known as the open API specification is a language-agnostic framework used to describe RESTful API. By reading the structure of the API, Swagger provides user-friendly and interactive API documentation.
Swagger provides the structure of an API and its metadata which is human and machine-readable. It provides information on a list of all the operations that the API supports, parameters that are expected by an endpoint, and the value it returns.
Why use Swagger?
User-friendly
Swagger comes with a user-friendly screen that describes the entire structure of the API. It enables not just developers, but also product managers, stakeholders, and testers to have a good understanding of the design of the API.
Human and machine-readable
It is not just friendly to users, it is machine-readable and it helps in automating the API dependent processes.
Helps to figure API problems
Using the Swagger UI, developers and testers can call the required endpoints with the appropriate input parameters for debugging and figuring out issues in the API.
Helps to build design-first API
Swagger provides a blueprint of the API which can be used to do the top-down approach. In other words, a design-first approach, where the endpoints and the required parameters are defined before even the actual business code is written.
Userbase
Swagger is backed by big companies and there are many people in the current world to help in case of problems or issues that developers face during the implementation of it.
Helps in testing and ensuring quality
Swagger's definition is machine-readable and it becomes a single source of truth for the API. This helps in testing each operation of the endpoint with the appropriate input. Also, API definitions can be imported into tools like Postman which can be used for manual testing.
Swagger tools for APIs
Swagger UI
Swagger UI is a collection of HTML, CSS, and JavaScript which is used to generate documentation for OpenAPI definition compliant APIs.
Swagger Editor
Swagger Editor is an open-source editor to design, define, and document APIs in the Swagger specification. It is available online at editor.Swagger.io. It is built on client-side JavaScript. The screen of the website is split into two halves where the left side contains the specifications of the API serialized in YAML format and the right side shows generated API documentation. Any edits that are made on the left side of the screen reflects on the right side documentation.
Swagger Codegen
Swagger Codegen is an open-source code generator that facilitates the dev process by generating server stubs and client SDKs. The development team can make use of this to build the API in a faster manner and always lets them focus on the adoption of it.
Swagger Inspector
Swagger Inspector allows users to validate and test APIs. It can be accessed from the browser using the URL - https://inspector.Swagger.io. The tests are auto-saved and can be accessed easily, as the details are stored in the user account.
Also, once the API is used for testing in the Swagger Inspector, it allows users to generate documentation for the same API, which can be handy for others.
Practical implementation of Swagger
In this section, let's see the step by step procedure on how to implement Swagger for a .net core based Web API.
Step 1
Create a new project with ASP .Net Core web application and provide a name for it.
Step 2
Choose ‘API’ as the web application type and click on the ‘Create’ button. Once the project is created, the solution would appear as below.
:
Step 3
Open the Nuget Package Manager window and Install the below packages into the project.
Swashbuckle.AspNetCore
Swashbuckle.AspNetCore.Swagger
Swashbuckle.AspNetCore.SwaggerUI
Step 4
After installing the packages, open the Startup.cs file and locate the method - ‘ConfigureServices’ and add the below line to it.
services.AddSwaggerGen();
Step 5
In the same startup.cs file locate the method - ‘Configure’ and add the below lines to it.
app.UseSwagger(c =>
{
c.SwaggerEndpoint(“/Swagger/v1/Swagger.json”,”My API v1”);
});
The API project comes with WeatherForecastController by default. And it has a Get method with few weather data in it. Let's try to access it using Swagger.
Step 6
Debug the API project locally. The project would open in a browser. From the base URL of the application, for example - https://localhost:44377 add /Swagger/index.html
https://localhost:44377/Swagger/index.html
On executing the above URL, Swagger for the API would be displayed in the browser with the only endpoint that is available in it.
Step 7
We can try to execute the endpoint from Swagger by clicking on the endpoint and selecting the ‘Try it out’ option. As this endpoint does not require any input data, you can directly click on the ‘Execute’ button.
On executing, the data appears along with the response status code.
Wrapping up
Swagger is one of the most powerful and useful tools in the API world. Features of Swagger makes the developers easier to automate the documentation process of APIs. So go ahead and try it out in your next web API.