[Management] OpenAPI specs

Requirements

• npm 3+ in your PATH
• gulp 3+ installed globally (npm install -g gulp)

Steps

1. Finalize your OpenAPI (a.k.a. Swagger) specs in azure-rest-api-sepcs repo.

2. Add your entry in the Java SDK gulp file. See Add an entry to gulp file.

3. Find out the client-runtime version & AutoRest version to use. See Which version should I use?.

4. Generate the code by executing

   gulp codegen --projects <service name> --autorest <autorest version>

5. Add a pom.xml file using another service as a template

6. Add your service to the parent pom.

Add an entry to gulp file

If you open gulpfile.js you can see a mapping defined on the top:

var mappings = {
    "compute": {
        "dir": "azure-mgmt-compute",
        "source": "arm-compute/2016-03-30/swagger/compute.json",
        "package": "com.microsoft.azure.management.compute",
        "args": "-FT 1"
    },
    ...
}

Add yours in it:

var mappings = {
    ...
    "<simple name>": {
        "dir": "azure-mgmt-<service>",
        "source": "<path to OpenAPI JSON>",
        "package": "com.microsoft.azure.management.<service>",
        "args": "-FT 1",
        "fluent": "true"
    },
    ...
}

Fields explained:

• <simple name> - this is the unique identifier user types in command line to generate the code, in lower case
• <service> - the name of your service, in lower case
• <path to OpenAPI JSON> - the relative path to your specs file in azure-rest-api-specs repo.
• fluent - Use false if there's no fluent interface built on top of the AutoRest generated code. This is usually true for management libraries, and false for data plane libraries.

Which version should I use?

Here is a table of compatible runtime and AutoRest:

Runtime version	AutoRest nightly version	Remarks
1.0.0-beta1	AutoRest 0.15.0	This is the last released version where ARM libraries are still simply auto-generated. Please use this if you expect your customers to use auto-generated resource, storage, compute, or network libraries. Danger: there have been many bug fixes since we released this in March. This can be outdated and we are deprecating it.
1.0.0-beta2	0.17.0-Nightly20160707
1.0.0-beta3	0.17.0-Nightly20161004