Skip to content

Latest commit

 

History

History
248 lines (188 loc) · 8.02 KB

configure-cli.md

File metadata and controls

248 lines (188 loc) · 8.02 KB
Raw

Readme Configuration Guide for Azure CLI

This file describe how to configure readme files to make it available for Azure CLI code generation.

Common Configuration

In order to use cli codegen. We need readme.az.md and readme.cli.md and readme.python.md to be ready.
where the readme.cli.md is the common configuration for all the command line tools like Azure CLI, Powershell, Terraform etc. not only for Azure CLI.
and the readme.az.md is specific configuration for Azure CLI. Because Azure CLI is calling Azure SDK for Python in the implementation layer. we need readme.python.md to be ready, we can refer to configure-python-sdk.md for more details about it.

Basic Information

Configure package title/description/tag.

// file: readme.md

``` yaml
title: xxxxConfigurationClient
description: xxxx Configuration Client
openapi-type: arm
tag: package-xxxx-xx-xx
```

tag

Tags are used to define what swagger files are used in specific client SDK. In Single-API client, only one tag can be used to generate SDK client. A tag can contains a bunch of swagger files which are used to generate the SDK.

The name of a tag should be in form of package-yyyy-mm-dd[-xxx], for example below tag names are available:

  • package-2020-02-03
  • package-2020-03-22-preview
  • package-2020-05-03-only

while the below tag names are invalid names:

  • 2020-03-04
  • package-preview-2020-03-04

A tag can be configured like below:

// file: readme.md


### Tag: package-2019-12-01

These settings apply only when `--tag=package-2019-12-01` is specified on the command line.

``` yaml $(tag) == 'package-2019-12-01'
input-file:
- Microsoft.Compute/stable/2019-12-01/compute.json
- Microsoft.Compute/stable/2019-12-01/runCommands.json
- Microsoft.Compute/stable/2019-12-01/gallery.json
```

Swagger to SDK

To make Azure SDK for Javascript (Typescript) can be generated from the tag, swagger-to-sdk need to be configured:

// file: readme.md

## Swagger to SDK

This section describes what SDK should be generated by the automatic system.
This is not used by Autorest itself.

``` yaml $(swagger-to-sdk)
swagger-to-sdk:
  - repo: azure-cli-extensions
  - ...


## AZ

See configuration in [readme.az.md](./readme.az.md)

Az Configuration

Az dedicated configurations are configured in readme.az.md. A typical readme.az.md is like this:

// file: readme.az.md

## AZ

These settings apply only when `--az` is specified on the command line.

``` yaml $(az) && $(target-mode) != 'core'
az:
    extensions: communication
    namespace: azure.mgmt.communication
    package-name: azure-mgmt-communication
az-output-folder: $(azure-cli-extension-folder)/src/communication
python-sdk-output-folder: "$(az-output-folder)/azext_communication/vendored_sdks/communication"
# add additional configuration here specific for Azure CLI
# refer to the faq.md for more details
```

where:

  1. the extensions means the name of the azure cli command modules,
  2. the namespace means the python SDK namespace,
  3. the package-name is the python SDK package name,
  4. the azure-cli-extension-folder is the parameter that will be passed by user in their commmand line which should points to their local azure-cli-extensions repo.
    Note: this parameter azure-cli-extension-folder is only for Azure CLI extensions and if user are targeting generate the Azure CLI main repo modules, the parameter should be azure-cli-folder that points to their local azure-cli repo.
  5. the az-output-folder is the specific output folder of this command modules. we should follow the basic code structure either in Azure CLI extensions or in Azure CLI main modules. If it is Azure CLI extensions that we are targeting, then the folder path should be like $(azure-cli-extension-folder)/src/{serviceFolderName}. If it's the Azure CLI main modules that we are targeting, then the folder path should be like $(azure-cli-folder)/src/azure-cli/azure/cli/command_modules/{serviceFolderName}.
  6. the python-sdk-output-folder is the vendored sdk path. Please Note that, even if we don't really generate the sdk, but we still need the folder path. It's worth notable that in the parts before and after vendored sdks are also configurable for specific user scenarios.

Note: it's better to add the yaml condition $(target-mode) != 'core' for generating cli extensions and $(target-mode) == 'core' for generating cli main modules. Make sure those configuration can only be accessed when wanted.

Multi-api

Currently the Azure CLI code generator doesn't support multi-api which means each operation contained in one package should only contains one api-version's.

Multi-packages

The batch is a tag list which are used in the one RP has multi-package scenarios. For example, the Migrate RP has two independent packages like migrate and offazure.
First of all, you need to have different yaml block for each package to define the default tag for that specific package.

// file: readme.md
## Configuration

### Basic Information

These are the global settings for the Resource API.

``` yaml
openapi-type: arm
```

``` yaml $(package-migrate)
tag: package-migrate-2019-10
```

``` yaml $(package-offazure)
tag: package-offazure-2020-01
```

Then for each default tag, you can define the input swagger like normal tag.


### Tag: package-migrate-2019-10

These settings apply only when `--tag=package-migrate-2019-10` is specified on the command line.

``` yaml $(tag) == 'package-migrate-2019-10'
input-file:
- Microsoft.Migrate/stable/2019-10-01/migrate.json
```

### Tag: package-offazure-2020-01

These settings apply only when `--tag=package-offazure-2020-01` is specified on the command line.

``` yaml $(tag) == 'package-offazure-2020-01'
input-file:
- Microsoft.OffAzure/stable/2020-01-01/migrate.json
```

Thirdly, in your readme.az.md you should include what packages you want to include in the Azure CLI. And in each package's section define the default package name output folder in azure-cli-extensions repo etc.

## AZ

These settings apply only when `--az` is specified on the command line.
``` yaml $(az)
batch:
    - package-migrate: true
    - package-offazure: true
```

``` yaml $(az) && $(package-migrate)
az:
  extensions: migrate
  namespace: azure.mgmt.migrate
  package-name: azure-mgmt-migrate
az-output-folder: $(azure-cli-extension-folder)/src/migrate
python-sdk-output-folder: "$(az-output-folder)/azext_migrate/vendored_sdks/migrate"
```

``` yaml $(az) && $(package-offazure)
az:
  extensions: offazure
  namespace: azure.mgmt.offazure
  package-name: azure-mgmt-offazure
az-output-folder: $(azure-cli-extension-folder)/src/offazure
python-sdk-output-folder: "$(az-output-folder)/azext_offazure/vendored_sdks/offazure"
```

Finally, you need to prepare the readme.python.md and readme.cli.md

// in readme.python.md file

## Python

``` yaml $(python)
python:
  azure-arm: true
  license-header: MICROSOFT_MIT_NO_VERSION
  payload-flattening-threshold: 2
  clear-output-folder: true
batch:
  - package-migrate: true
  - package-offazure: true
```

``` yaml $(python) && $(package-migrate)
python:
  package-version: 0.1.0
  namespace: azure.mgmt.migrate
  package-name: azure-mgmt-migrate
  basic-setup-py: true
  output-folder: $(python-sdks-folder)/migrate/azure-mgmt-migrate
```

``` yaml $(python) && $(package-offazure)
python:
  package-version: 0.1.0
  namespace: azure.mgmt.offazure
  package-name: azure-mgmt-offazure
  basic-setup-py: true
  output-folder: $(python-sdks-folder)/offazure/azure-mgmt-offazure
```

// in readme.cli.md file

``` yaml
# add any configuration here for all CLI languages
# refer to the faq.md for more details

Run codegen

After configure all the readme files, autorest can be used to generate SDK.

autorest --az --use=@autorest/az@latest /home/qiaozha/code/azure-rest-api-specs/specification/storage/resource-manager/readme.md --azure-cli-extension-folder=../azure-cli-extensions

Advance Usage

For advance usage of CLI Codegen, Please refer to autorest.az doc