Skip to content

Generate a Python SDK from a Swagger file

Jump to bottom
Laurent Mazuel edited this page Dec 5, 2017 · 35 revisions

This document provides instructions and guidelines on how to generate a Python SDK from a Swagger file.

Table of contents:

Step 1: Generating your first client for local testing

If you're discovering Python for the first time, we have great intros using Notebooks on Azure. Click the "Show me more samples" button to see them.

Once you're comfortable with Python:

  • You need to install Autorest: aka.ms/autorest/install. Minimal Autorest version is "2.0.4215". Please refer to the Autorest CLI doc for details about parameters.

  • To call Autorest, you need the following options:

    • Required parameter: --payload-flattening-threshold=2

    • About the generator:

      • If your endpoint is ARM, add --python --azure-arm=true
      • If not, add --python. If your client might ask authentication, add --add-credentials

And that's it! You should now have Python code ready to test. Note that this generation is for testing only and should not be sent to a customer or published to PyPI.

This command generate code only. If you want to generate a wheel file to share this code, add the --basic-setup-py option to generate a basic setup.py file and call python setup.py bdist_wheel.

Example

ARM management Swagger:

autorest --version=latest --python --azure-arm=true --payload-flattening-threshold=2 --input-file=myswagger.json

Not-ARM Swagger:

autorest --version=latest --python --payload-flattening-threshold=2 --add-credentials --input-file=myswagger.json

Step 2: Generating your first client that you want to release

Generate a package

First, your Swagger needs to at least be a PR in the official Microsoft Swagger RestAPI repo. This allows you to determine the name of your future package.

  • If your folder looks like specifications/myservice/resource-manager
    • Your package name will be azure-mgmt-myservice
    • Your namespace will be with azure.mgmt.myservice
  • If your folder looks like specifications/myservice/data-plane
    • Your package name will be azure-myservice
    • Your namespace will be with azure.myservice

For example, the specification/compute/resource-manager folder will create the package azure-mgmt-compute and will use the namespace azure.mgmt.compute.

Let's assume for now that your Swagger is in specification/compute/resource-manager

To call Autorest, you need the following options:

  • Required parameters:

    --payload-flattening-threshold=2 --license-header=MICROSOFT_MIT_NO_VERSION --namespace=azure.mgmt.compute --package-name=azure-mgmt-compute --package-version=0.1.0

  • About the generator:

    • If your endpoint is ARM, add --python --azure-arm=true
    • If not, add --python. If your client might ask authentication, add --add-credentials

Example

ARM Swagger with MD (preferred syntax):

autorest --version=latest specifications/storage/resource-manager/readme.md --python --azure-arm=true --payload-flattening-threshold=2 --license-header=MICROSOFT_MIT_NO_VERSION --namespace=azure.mgmt.storage --package-name=azure-mgmt-storage --package-version=0.1.0

ARM Swagger without MD (if you have an excellent reason):

autorest --version=latest --python --azure-arm=true --payload-flattening-threshold=2 --license-header=MICROSOFT_MIT_NO_VERSION --namespace=azure.mgmt.storage --package-name=azure-mgmt-storage --package-version=0.1.0 --input-file=specifications/storage/resource-manager/Microsoft.Storage/2016-12-01/storage.json

Testing

We recommend you to test your package. We made a tutorial to help you with this process: https://github.com/Azure/azure-sdk-for-python/wiki/Contributing-to-the-tests

Note this is not mandatory, but testing is important, and Autorest has regularly issues that can only be seen in one specific client in one specific context (so code generation does not protect you from bugs)

Create a PR on the repo

You can create a PR on this repo with your package. Submit at the root of the repo the folder called azure-<something>

Example: if your package name is azure-mgmt-logic, Autorest will generate a azure-mgmt-logic folder. Submit this folder at the root.

You must update this file using a CookieCutter template published here. Command is (from the root of the repo):

cookiecutter.exe -f gh:Azure/cookiecutter-azuresdk-pypackage

You will be told three questions. Question 1 must be the name of your package (i.e. azure-mgmt-logic), question 2 should be left at the default value, question 3 must be the "pretty name" of your package (i.e. Logic Management).

In your PR, you need to update the configuration file called swagger_to_sdk_config.json as well.

A typical new entry looks like this:

   "logic": {
      "markdown": "specification/logic/resource-manager/readme.md",
      "autorest_options": {
        "namespace": "azure.mgmt.logic",
        "package-name" : "azure-mgmt-logic",
        "package-version": "2.0.0"
      },
      "output_dir": "azure-mgmt-logic/azure/mgmt/logic",
      "build_dir": "azure-mgmt-logic"
    },

This will be used by the CI to update your package automatically in the future.

You must update in your PR the package_service_mapping.json to allow your documentation to be on docs.microsoft.com:

	"azure-mgmt-containerregistry": {
		"service_name": "Container Registry",
		"category ": "Management",
                "namespaces": [
                    "azure.mgmt.containerregistry"
                ]
	},

Step 3: Updating your package

When you have a PR merged on https://github.com/Azure/azure-rest-api-specs, if your configuration file is up to date, then a PR will be automatically created here. The link will appear in your Swagger PR. You can review the Python PR and comment on it if necessary (even just a LGTM).

Step 4: Releasing to PyPI

We have no private server to mock PyPI for testing. However, Python is able to install a package "like it was in PyPI" from Github with the following command (example here for azure-mgmt-consumption)

pip install "git+https://github.com/Azure/azure-sdk-for-python#subdirectory=azure-mgmt-consumption&egg=azure-mgmt-consumption"

To insure all packages are released correctly and meets the quality we expect (for instance, there is some tricky configuration details on how to build the package to improve the performance on the client machine), only us in the Python team can release on PyPI for now.

Clone this wiki locally