How To Create REST API Service Client Using Swagger And REST API Client Tool

Introduction

 

In this article, we will learn how to generate a Swagger specification document for our Web API Service and how to create a client for API service by using Swagger and Visual Studio REST API Client Tool. If you have Swagger metadata files or a Swagger Url then Visual Studio has provided a REST API Client Tool to consume REST API services in the project. Before creating Swagger specifications and a client for REST API, first let’s learn about Swagger.

 

What is Swagger?

 

Swagger is a Web API specification document that helps developers design, build, document, and consume RESTfulweb services. Swagger tools support automated documentation, code generation, and test-case generation. Swagger asks Web APIs to return a YAML or JSON that contains a detailed specification of the entire API.

 

The Swagger specification provides information about APIs like,

• All the operations that API supports
• API’s parameters and return type
• API objects structure
• API authorization
• License to use the API etc.

For more details about Swagger specification visit here.

 

How to add Swagger to the REST Web API service?

 

To add Swagger to Web API, we need to install Swashbuckle via NuGet. The following are the steps for this.

 

Step 1

 

For this, I have created a ContactAPI solution and project. Right-click on API Project References and select Manage NuGet Packages.

 

 

Step 2

 

On NuGet screen Browse for “SwashBuckle” and click on install.

 

 

Step 3

 

After installation, you can see the SwaggerConfig.cs class file under the app_start folder. In SwaggerConfig class under Register Method by default Swagger and SwaggerUI configuration are already enabled. You can enable other options also as per your requirement.

GlobalConfiguration.Configuration
.EnableSwagger(c => { c.SingleApiVersion("Version", "Project Name");})
.EnableSwaggerUi(c =>{});

Step 4

 

Now, Run your API application, and type the word “swagger”  after service URL. For example http://localhost:59423/swagger/

 

It will open a UI with the API specifications.

 

 

Step 5

 

On screen, you can see a URL in Swagger UI, for example, http://localhost:59423/swagger/docs/v1. Copy-paste this URL in another tab and you will get Swagger metadata. Save this metadata in a file as a “.JSON” extension.

 

 

This is the API Swagger URL and metadata file which you can share with other teams to consume and create a client for API service. To view generated Swagger specifications using metadata you can also use https://editor.swagger.io/ tool. On this tool at the left side, you can copy & paste metadata information and it will provide API information at the right-hand side.

 

 

How to create an API Client using Visual Studio REST API Client tool?

 

To create a client for shared Swagger specifications, you can either do it manually, or you can use Visual Studio to build the REST API Client tool. Here I am using the REST API Client tool.

REST API Client tool creates and adds necessary packages, model classes and testable, dependency injectable HttpClient classes using Swagger specifications in your project.

 

Step 1

 

You can create any type of project like MVC, Console or Class project to generate a client for API. I have created the “ContactAPIClient” MVC project to generate a client for API.

 

Now, right-click on the project and select “Add” and click on the “REST API Client” option.

 

 

Step 2

 

On selecting REST API Client, it will open the tool where you can either provide Swagger Url or you can select Swagger metadata file from your local drive.

 

 

Step 3

 

Once you click on the “OK” button after selecting the Url or metadata file option, the tool will create model classes and necessary client classes and add packages for you.

 

The tool adds to Microsoft.Rest.ClientRuntime dll under References, and creates a folder in project (for my example it is “ContactAPI”) with API service model classes, necessary interfaces and client classes for you. For my example the tool has created the below 5 partial classes and interfaces. Sometimes it creates 3 partial class files also and it combined IContactAPI and IContacts interface in one.

1. IContactAPI: interface.
2. ContactAPI: class which implements IContactAPI interface.
3. IContacts: interface.
4. Contacts: a class that implements the IContacts interface.
5. ContactsExtensions: class which is having extension methods.

 

Step 4

 

You can find all constructors are parameterized and protected under ContactAPI.cs class. If you have a requirement where you have to pass parameter values, then you can use any one available constructor. To keep the example simple, I have added a new public parameterless constructor like below in ContactAPI.cs class.

public ContactAPI()
{
     this.Initialize();
}

Step 5

 

Now go to the MVC controller where you want to consume this client. Create a client object and pass values to API functions. For example:

ContactRequest request = new ContactRequest { ContactID = 1 };
using(var client = new ContactAPI())
{
        ContactResponse response = client.Contacts.GetContact(request.ContactID);
}

Conclusion

 

In this article, we learned how to generate a Swagger specification, and if we have a Swagger specification then how to create REST API Service client using Visual Studio REST API Client tool.

 

I hope this helps you. Thanks.