Skip to content

Generate a Python SDK from a Swagger file

Jump to bottom
Laurent Mazuel edited this page Apr 13, 2017 · 35 revisions

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

Table of contents:

Step 1: First client, you want to test locally

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

  • You need to install Autorest: aka.ms/autorest/install

  • To call Autorest, you need the following options:

    • Required parameter: -ft 2

    • About the generator:

      • If your endpoint is ARM, add -g Azure.Python
      • If not, add -g Python. If your client might ask authentication, add -AddCredentials true

    • If your input is a Composite file, add -Modeler CompositeSwagger

Example: autorest --version=latest -i myswagger.json -g Azure.Python -ft 2

And that's it, you 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.

Step 2: First client, you want an Azure package to release

Generate a package

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

  • If your root folder is prefixed by arm-:
    • Your package name will be prefixed by azure-mgmt-
    • Your namespace will start by azure.mgmt
  • If not:
    • Your package name will be prefixed by azure-
    • Your namespace will start by azure

Example, the arm-compute folder will create the package azure-mgmt-compute and will use the namespace azure.mgmt.compute.

Let's assume from now that your Swagger is in arm-compute

To call Autorest, you need the following options:

  • Required parameters:

    -ft 2 -Header MICROSOFT_MIT_NO_VERSION -Namespace azure.mgmt.compute -PackageName azure-mgmt-compute -PackageVersion 0.1.0

  • About the generator:

    • If your endpoint is ARM, add -g Azure.Python
    • If not, add -g Python. If your client might ask authentication, add -AddCredentials true

  • About the modeler, if your file is Composite file, add -Modeler CompositeSwagger

Example: autorest --version=latest -i arm-compute/compositeComputeClient.json -g Azure.Python -ft 2 -Header MICROSOFT_MIT_NO_VERSION -Namespace azure.mgmt.compute -PackageName azure-mgmt-compute -PackageVersion 0.1.0 -Modeler CompositeSwagger

Create a PR on the repo

You can create a PR on this repo with your package. Create at the root a folder with the name of your package and put the files generated by Autorest inside. If you did it correctly, you should see in your folder a setup.py file generated by Autorest.

Example: if your package name is azure-mgmt-logic, create a azure-mgmt-logic folder at the root and put the Autorest files inside in a way that azure-mgmt-logic/setup.py exists.

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

A typical new entry looks like this:

   "logic": {
      "swagger": "arm-logic/2016-06-01/swagger/logic.json",
      "autorest_options": {
        "Namespace": "azure.mgmt.logic",
        "PackageVersion": "2.0.0"
      },
      "output_dir": "azure-mgmt-logic/azure/mgmt/logic"
    },

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

You're also encouraged to create tests for your package in the PR. We made a contribute to the tests tutorial.

Step 3: I updated my Swagger

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 it if necessary (even just a LGTM).

Step 4: I have a new ApiVersion, or my Modeler change (Composite/not-composite)

Open a PR here with the update in the configuration file for your project.

  • If your Swagger PR is not merged yet, that's it: your package will be updated when the Swagger PR will be merged.
  • If your Swagger PR is already merged, there is no automatic way to regenerate your package. You can regenerate manually yourself and PR the change, or you can simulate the CI (there is a process for that) or simply ask me @lmazuel to do it.

Step 5: What about release?

To insure all packages are released correctly and meets the quality we expect (for instance, there is some tricky configuration 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