How to Automatically Generate Clients for your REST API
Create client code in seconds for all popular languages, and save hours of repetitive manual labor.
Chances are, if you’re developing RESTful APIs, you’ve heard of the OpenAPI specification (formerly known as Swagger) before. The OpenAPI Specification defines a standard interface to describe an API, regardless of the language it was written in. This specification can then be used to automatically create documentation based on conventions, or to automatically generate clients for your services.
Modern application landscapes often comprise of many independent services. Each of these services have one or more responsibilities, and have an interface to expose functionality to the outside world. In the case of RESTful services, this functionality is exposed over HTTP. Writing client code to interface with these services is often a very repetitive, slightly tedious task.
Fortunately, with the power of Microsoft’s AutoRest code generator, we can automatically generate client code for almost every popular language or framework out there.
In this guide, you’ll learn how to set up AutoRest to leverage the OpenAPI specification, and to generate a client for you. We’ll be using an ASP.NET Core Web API in the example code, but the process is much the same for any other language or framework.
What you’ll need:
- NodeJS — 10.15.x LTS is the preferred version at the time of writing, but any LTS version should be fine
- An API with an OpenAPI specification. You can also grab the API that’s used for this guide from GitHub and run it if you have the .NET SDK installed
Notes for the Sample API
If you decide to use the sample API to follow along with this guide, there are a couple of additional things you’ll need:
- Visual Studio or Visual Studio Code. The former comes with the .NET Core 3.1 SDK, the latter doesn’t. If needed, you can download the .NET SDK from the official website.
- By default, the API serves content on port 5000. You can change this in
Properties/launchSettings.jsonif that port doesn’t work for you.
- If you are using Visual Studio, everything should be good to go once you hit F5. If you’re using another editor, you may need to
dotnet runit to work.
With that out of the way, let’s get started!
AutoRest is a tool created and maintained by Microsoft that generates clients for RESTful web services, taking an OpenAPI specification as its input.
We’ll install AutoRest as a global NPM package:
npm install -g autorest
This may take a few minutes. After which, you can test whether AutoRest installed successfully by running
autorest --help , which will output all the available commands to your console.
If you ever need to update AutoRest, you can simply run:
And it will update itself to the latest version. As of writing, the latest version is AutoRest 3.0, which introduced support for the OpenAPI 3 Specification.
Generating the Client
In the previous step, we’ve installed AutoRest. Next up is grabbing the OpenAPI specification from our API, and feeding it to the AutoRest code generator.
Make sure your API is running and that the OpenAPI endpoint is reachable. For the sample code used in this guide, our endpoint is:
But of course, this may be different depending on your setup. Next up, we’ll be grabbing that
swagger.json file and we’ll write it to a
docs folder. Personally, I always keep the specification alongside the code in the repository. This allows you to keep track of changes made to the specification, as well as gives you the spec that was used to generate the client alongside the client itself.
Copying the Specification
If you are using Windows, you can use the following PowerShell command to create the directory we’ll be writing our specification to, and grab it over HTTP:
New-Item -ItemType Directory -Force -Path ./docs/openapiiwr http://localhost:5000/swagger/v1/swagger.json -o ./docs/openapi/api-v1.json
If you’re using Linux, some variation of the following should work:
Make sure the path
./docs/openapi/swagger.json is valid, and that the JSON file contains your API’s spec.
Feeding the Specification to AutoRest
Now that we have a local copy of our specification, all that’s left is feeding it to AutoRest. AutoRest has a bunch of options, including a ton of language switches you can use to specify what language the client should be written in.
We’ll be using the C# language switch in this guide, but you can also substitute it with any of the following:
Among others. Refer to the Generators section of the AutoRest readme to see all supported languages.
Another interesting switch is the
--sync-methods switch. This dictates whether or not AutoRest should generate synchronous methods alongside asynchronous one. This may not work for all languages. Personally, for the majority of cases I recommend not generating synchronous members at all due to the asynchronous nature of these calls.
I highly recommend you check out the command line interface documentation to see if there are other options that may apply to your use-case.
All that’s left is the actual call to AutoRest:
autorest --input-file=./docs/openapi/api-v1.json --v3 --csharp --use-datetimeoffset=true --sync-methods=none --output-folder=./src/SampleApi.Client --namespace=SampleApi.Client
After this command runs successfully, your client resides in the specified output folder.
For our sample code, the client would be instantiated and used as follows:
var client = new SampleAPI(new Uri("http://localhost:5000"));var weatherForecast = await client.GetAsync();
weatherForecast will now contain an array of forecast predictions.
That’s all there’s to it!
We’ve generated a web service client based on its OpenAPI specification using AutoRest in C#. Client generation can be fully automated and requires no manual work anymore.
Depending on how your projects are structured, you could integrate this into your Continuous Integration workflow to always ship up-to-date clients for anyone interesting in using your APIs.
You can also ship clients in languages other than the one your API was developed in, to attract and enable interaction with a broader range of developers.
Thanks for reading, and I hope you can use this in your daily work!