Skip to content

Latest commit

 

History

History
57 lines (35 loc) · 4.32 KB

swagger_conf.md

File metadata and controls

57 lines (35 loc) · 4.32 KB

Swagger configuration

All management SDK comes from a Swagger, processed by autorest. This page explains how to use autorest to generated Python code.

Overview

Nowadays, swagger files are actually not the input for Autorest, the input is readme.md file. This file contains all the configuration necessary in order to generate a correct Python code, making the generation as simple as:

autorest readme.md --python

In practical terms, we want to control the version of Autorest used, the output folder, etc. but this article will focus on Swagger and Readme. For more details about generation, see the generation page.

Writing the readme

Writing the readme is the responsibility of the Python SDK team. There is currently two types of templates for Python readmes:

  • Readme that handles only one API version, and generates packages that handle one API version only
  • Readme that handles several API versions, and generates packages with multiples API and profile supports

These templates can be found in the single_api and the multi_api folders.

Single API readmes

This one is the most simple:

  • Copy the readme.python.md and replace servicetoreplace by your service name
  • Be sure the main readme.md contains a "swagger-to-sdk" section with Python

Multi API readmes

When doing multi-api packages, it means you have shipping several "tags" of the main readme as one package. Autorest is calling this process a "batch" call, and this is the purpose of the "batch" section in readme.python.md.

In order to be sure the correct tags exist, you can use the following script:

python ./scripts/multi_api_readme_help.py /azure-rest-api-specs/specification/service/resource-manager/

This script will analyze the Swaggers available, and suggests on stdout:

This script is not perfect that it does require manual review of the output and not a direct copy/paste.

It's important for Python that tags represents only ONE unique API version. It's why it's pretty common that Python uses a set of tags that other languages don't use.

Once you know the list of tags you need to generate:

  • Copy the readme.python.md and replace servicetoreplace by your service name
  • Update the batch list of readme.python.md
  • Be sure you have one tag section for each batch entry in readme.python.md
  • Be sure the main readme.md contains a "swagger-to-sdk" section with Python with an afterscripts section like the one in the template.

The afterscripts will execute a Jinja template to create a client to link together all the batch generated autorest (example)

This script will infer a default LATEST_PROFILE. You can change this behavior and force the default API version if necessary (example)