Swagger (OpenAPI) Specification code generator featuring C# and Razor templates. Supports C#, Java, Node.js, TypeScript, Python and Ruby.
C# Java JavaScript Python Ruby TypeScript Other
Permalink
Failed to load latest commit information.
PackageTest Promote RefactorCodeModel to master (#1545) Nov 2, 2016
Samples [Ruby] Making credentials nil by default (#1677) Jan 11, 2017
Tools Improvements for Mono & Docker users (#1714) Jan 13, 2017
docs Improvements for Mono & Docker users (#1714) Jan 13, 2017
gradle/wrapper Include required jar for gradle wrapper Nov 16, 2015
schema added operationId and title as optional properties of the example sch… Jan 17, 2017
src Fix for list and dict serialization (#1727) Jan 20, 2017
.gitattributes Fixing C# simplifier, and line endings in generated code. (#1627) Nov 19, 2016
.gitignore Generate Server side code from specs (#1697) Jan 6, 2017
.ruby-version add in a root level gemfile so that we will have all ruby test depend… Jul 28, 2015
.travis.yml Fixing java issue in travis? Dec 5, 2016
AutoRest.sln CSharp.Azure.Fluent refactor and some Go fixes (#1705) Jan 5, 2017
AutoRest.sln.DotSettings Promote RefactorCodeModel to master (#1545) Nov 2, 2016
ChangeLog.md Adding release notes for 0.16.0 release May 11, 2016
Gemfile Updated gemfiles to support faraday. Aug 7, 2015
Issues.md Page with links to Issues Queries Jun 15, 2016
LICENSE update copyright year Aug 19, 2016
README.md Improvements for Mono & Docker users (#1714) Jan 13, 2017
build.gradle Java beta2 release (#1213) Jun 29, 2016
build.proj Generator should not flatten out parameters if they are polymorphic (#… Jan 18, 2017
global.json Moving Clientruntimes out of autorest Oct 5, 2016
gradle.properties Move gradle properties into a centralized one Jan 22, 2016
gradlew chmod +x gradlew Nov 16, 2015
gradlew.bat Add gradlew wrapper for easier developer setup Nov 16, 2015
gulpfile.js CSharp.Azure.Fluent refactor and some Go fixes (#1705) Jan 5, 2017
package.json Bumped up gulp npm versions May 25, 2016
settings.gradle Re-organize entire code repo (#1220) Jul 6, 2016

README.md

Repo Status Issue Stats Issue Stats

AutoRest

The AutoRest tool generates client libraries for accessing RESTful web services. Input to AutoRest is a spec that describes the REST API using the Open API Initiative format.

Getting AutoRest

The AutoRest tools can be installed with Nuget for use in a Visual Studio project: AutoRest NuGet

Alternatively it can be installed from Chocolatey by running: AutoRest Chocolatey

choco install autorest

Nightlies are available via MyGet: AutoRest MyGet

AutoRest can be run on macOS and *nix using Mono:

# Download & Unpack Autorest curl -LO https://github.com/Azure/autorest/releases/download/AutoRest-0.16.0/autorest.0.16.0.zip && \ unzip autorest.0.16.0.zip -d autorest/ && \ cd autorest && \

# Download Swagger.json example curl -O https://raw.githubusercontent.com/Azure/autorest/master/Samples/petstore/petstore.json && \

# Run AutoRest using mono mono AutoRest.exe \ -CodeGenerator CSharp \ -Input petstore.json \ -OutputDirectory CSharp_PetStore -Namespace PetStore

Or Docker:

# Download Swagger.json example curl -O https://raw.githubusercontent.com/Azure/autorest/master/Samples/petstore/petstore.json

# Download latest AutoRest Docker image docker pull azuresdk/autorest:latest

# Run AutoRest using Docker, mounting the current folder (pwd) into /home inside the container docker run -it --rm -v $(pwd):/home azuresdk/autorest:latest autorest \ -CodeGenerator CSharp \ -Input /home/petstore.json \ -OutputDirectory /home/CSharp_PetStore -Namespace PetStore

Building AutoRest

AutoRest is developed primarily in C# but generates code for multiple languages. See this link to build and test AutoRest.

Hint: There is a powershell script (verify-settings.ps1) in the Tools folder that can verify that you have the required compilers/tools/libraries installed on your development system before trying to build.

Hello World

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.


This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.