The AutoRest tool generates client libraries for accessing RESTful web services. Input to AutoRest is a spec that describes the REST API using the Swagger format.
##Getting AutoRest
The AutoRest tools can be installed with Nuget for use in a Visual Studio project:
Alternatively it can be installed from Chocolatey by running:
choco install autorest
Nightlies are available via MyGet:
AutoRest is developed primarily in C# but generates code for multiple languages. To build and test AutoRest requires a few things be installed locally.
Install the Microsoft Build Tools or get them with Visual Studio. Ensure that msbuild is in your path by running vcvarsall.bat
C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat
To compile the code in Visual Studio IDE,
- Ensure you are using Visual Studio 2015
- Ensure "Nuget Package Manager For Visual Studio" is updated to a newer version, like "2.8.60723.765", which is needed to install xunit.
- Install Task Runner Explorer to run gulp tasks such as synchonize nuget version, assembly info, etc.
Install DNVM using these steps and configure DNX 1.0.0-rc1.
Install Mono 4.3.0 (MonoFramework-MDK-4.3.0.372.macos10.xamarin.x86.pkg)
Install DNVM using these steps.
Install the latest from nodejs.org. Then from the project root run npm install
.
Install the latest Java SE Development Kit from Java SE Downloads.
Ensure that the JDK binaries are in your PATH
.
set PATH=PATH;C:\Program Files\java\jdk1.8.0_45\bin
Ensure that your environment includes the JAVA_HOME
.
set JAVA_HOME=C:\Program Files\java\jdk1.8.0_45
Install the latest Android environment from http://developer.android.com/sdk/index.html. You can either install Android Studio if you want to do actual development work in Android, or simply install the SDK tools that is minimally requried to build the Android code.
In SDK Manager, make sure that build tools >23.0.1, Android Support Repository, and Google Repository are installed. Make sure ANDROID_HOME is in your environment variable. If you installed Android Studio, you can find it out from Android Studio settings. If you installed SDK tools, its default location is C:\Program Files (x86)\Android\android-sdk
on Windows.
Install the Gradle build system
from Gradle downloads.
Ensure Gradle is in your PATH
.
set PATH=PATH;C:\gradle-2.6\bin
Ensure that your environment includes the GRADLE_HOME
.
set GRADLE_HOME=C:\gradle-2.6
You may want a Java IDE.
- Install Jetbrains IntelliJ IDEA from JetBrains downloads OR
- Install
Eclipse IDE for Java EE Developer
from Eclipse downloads
RubyInstaller version 2+ - 32-bit version.
By default, Ruby installs to C:\Ruby21 or Ruby22, etc. Ensure that C:\Ruby21\bin is in your PATH
.
set PATH=PATH;C:\Ruby21\bin
RubyDevKit 32-bit version for use with Ruby 2.0 and above The DevKit installer just unpacks files. Navigate to the directory and run the following:
ruby dk.rb init
ruby dk.rb install
gem install bundler
Install Python 2.7 and Python 3.5, and add one of them to your PATH (we recommend 3.5).
set PATH=PATH;C:\Python35
We use gulp and msbuild / xbuild to handle the builds. Install for global use with
npm install gulp -g
If you would like to see what commands are available to you, run gulp -T
. That will list all of the gulp tasks you can run. By default, just running gulp
will run a build that will execute clean, build, code analysis, package and test.
[13:54:21] Using gulpfile ./autorest/gulpfile.js
[13:54:21] Tasks for ./autorest/gulpfile.js
[13:54:21] ├── regenerate:expected
[13:54:21] ├── regenerate:delete
[13:54:21] ├── regenerate:expected:csazure
[13:54:21] ├── regenerate:expected:cs
[13:54:21] ├── clean:build
[13:54:21] ├── clean:templates
[13:54:21] ├── clean:generatedTest
[13:54:21] ├─┬ clean
[13:54:21] │ ├── clean:build
[13:54:21] │ ├── clean:templates
[13:54:21] │ └── clean:generatedTest
[13:54:21] ├── syncNugetProjs
[13:54:21] ├── syncNuspecs
[13:54:21] ├─┬ syncDotNetDependencies
[13:54:21] │ ├── syncNugetProjs
[13:54:21] │ └── syncNuspecs
[13:54:21] ├── build
[13:54:21] ├── package
[13:54:21] ├── test
[13:54:21] ├── analysis
[13:54:21] └── default
Prior to executing gulp
to build and then test the code, make sure that the latest tools are setup for your build environment.
- run
bundle install
from the root directory
For this version of Hello World, we will use AutoRest to generate a client library and use it to call a web service. The trivial web service that just returns a string is defined as follows:
public class HelloWorldController : ApiController
{
// GET: api/HelloWorld
public string Get()
{
return "Hello via AutoRest.";
}
}
By convention, Swagger documents are exposed by web services with the name swagger.json
. The title
property of the info
object is used by AutoRest as the name of the client object in the generated library. The host
+ path
of the operation corresponds to the URL of the operation endpoint. The operationId
is used as the method name. The spec declares that a GET
request will return an HTTP 200 status code with content of mime-type application/json
and the body will be a string. For a more in-depth overview of swagger processing, refer to Defining Clients With Swagger section of the documentation.
{
"swagger": "2.0",
"info": {
"title": "MyClient",
"version": "1.0.0"
},
"host": "swaggersample.azurewebsites.net",
"paths": {
"/api/HelloWorld": {
"get": {
"operationId": "GetGreeting",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "GETs a greeting.",
"schema": {
"type": "string"
}
}
}
}
}
}
}
Next, we invoke AutoRest.exe with this swagger document to generate client library code (see Command Line Interface documentation for details).
AutoRest is extensible and can support multiple types of input and output. AutoRest.exe comes with the AutoRest.json configuration file that defines the available inputs (Modelers) and outputs (CodeGenerators). When invoking AutoRest.exe, if you don't specify the -Modeler
then Swagger is assumed and if you don't specify -CodeGenerator
then CSharp is used.
The Swagger schema is language agnostic and doesn't include the notion of namespace, but for generating code, AutoRest requires -Namespace
be specified. By default, the CodeGenerator will place output in a directory named Generated. This can be overridden by providing the -OutputDirectory
parameter.
AutoRest.exe -CodeGenerator CSharp -Modeler Swagger -Input swagger.json -Namespace MyNamespace
Now, we will use the generated code to call the web service.
Create a console application called HelloWorld. Add the generated files to it. They won't compile until you add the NuGet package the generated code depends on: Microsoft.Rest.ClientRuntime
.
You can add it to the Visual Studio project using the NuGet package manager or in the Package Manager Console with this command:
Install-Package Microsoft.Rest.ClientRuntime
Add the namespace that was given to AutoRest.
using MyNamespace;
Access the REST API with very little code (see Client Initialization and Client Operations for details).
var myClient = new MyClient();
var salutation = myClient.GetGreeting();
Console.WriteLine(salutation);
Running the console app shows the greeting retrieved from the service API.
C:\>HelloWorld.exe
Hello via AutoRest.
With that same basic pattern in place, you can now explore how different REST API operations and payloads are described in Swagger and exposed in the code generated by AutoRest.