зеркало из https://github.com/Azure/autorest.az.git
Update how-to-generate.md (#727)
* Update how-to-generate.md * Update how-to-generate.md * Update how-to-generate.md * Update how-to-generate.md Co-authored-by: Qiaoqiao Zhang <55688292+qiaozha@users.noreply.github.com>
This commit is contained in:
kingces95
GitHub
Родитель
237047f3cb
Коммит
0d9d62903d
|
|
@ -1,72 +1,34 @@
|
|||
# Background knowledge
|
||||
|
||||
Autorest.az supports two kinds of code genreation now: full and incremental. Their description are as following:
|
||||
* Full: generate full Az Cli code for RP. All files will be generated.
|
||||
* Incremental: generate Az Cli code based on existing Az Cli code. The existing code will not change, while new generated code will be integreated into existing code.
|
||||
Autorest.az supports both Azure CLI main modules generation and Azure CLI extension generation.
|
||||
|
||||
Currently, autorest.az only support generate code target to cli extension repo. Target to cli repo will be supported soon.
|
||||
There are 3 approaches to use autorest.az:
|
||||
* **Swagger** repo pull request
|
||||
* **Docker**
|
||||
* **Locally** running autorest command
|
||||
|
||||
There are totally 3 approaches to use autorest.az now:
|
||||
* Through PR in **Swagger repo**
|
||||
* Through **Docker**
|
||||
* Through autorest command directly in **local**
|
||||
Note: Azure CLI main modules generation currently doesn't support Swagger PR generation.
|
||||
|
||||
The following tables shows that which approaches can be used for different scenarios:
|
||||
## Azure CLI main modules and Azure CLI Extensions
|
||||
|
||||
Approaches | Cli | Cli Extension
|
||||
-----------|-----|--------------
|
||||
Full | N/A | All approaches
|
||||
Incremental| N/A | **Docker** and **Local**
|
||||
* Azure CLI main modules: is the Azure CLI main modules, it targets https://github.com/Azure/azure-cli repo.
|
||||
* Azure CLI Extensions: is the Azure CLI extension modules, it targets https://github.com/Azure/azure-cli-extensions repo.
|
||||
|
||||
The preparation and autorest command for full/incremental, target to cli/cli-extension may have difference. The following will talk it.
|
||||
The difference between Azure CLI main modules and Azure CLI extension is very minimal for customer user experience. and currently CLI team is trying to migrate all the Azure CLI main repo modules into CLI extensions to keep main modules repo slighter.
|
||||
|
||||
## Full codegen to cli extension
|
||||
* **Readme**: [Preparing Readme](how-to-author-readme-file.md).
|
||||
* **Autorest command**:
|
||||
As autorest.az support auto detect full/incremental generation mode. The rule is:
|
||||
* If cli extention folder for target RP is empty, or not empty but code is generated by az code generator before, full code generation mode will be run.
|
||||
* If cli extention folder for target RP is not empty and the code is generated manually before, incremental code generation mode will be run.
|
||||
**Here're some guidelines before you decide whether you want main modules or CLI extensions and how our CLI code generator can better works:**
|
||||
|
||||
You can just using the following command for full code generation target to cli extension repo.
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder={azure_cli_ext_folder} {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
You can also add --generation-mode=full to force generate full code as following:
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder={azure_cli_ext_folder} --generation-mode=full {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
|
||||
## Incremental codegen to cli extension
|
||||
* **Readme**: Besides following [Preparing Readme](how-to-author-readme-file.md). Incremental contents need also be configure in the Readme.az.md file. There are two type of configure:
|
||||
* **Allow list** will use hidden flag to hide all command first. Then unhide the command group or command which need to be incremental generated. The sample are as following:
|
||||
|
||||
|
||||
* **Deny list** also use hidden flag. But it will directly hide the command which has been implement before. The sample are as following:
|
||||
|
||||
|
||||
|
||||
* **Autorest command**:
|
||||
As autorest.az support auto detect full/incremental generation mode. The rules are list [Here](how-to-generate.md#L27-L28). You can just using the following command for full code generation target to cli extension repo.
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder={azure_cli_ext_folder} {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
You can also add --generation-mode=incremental to force generate full code as following:
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder={azure_cli_ext_folder} --generation-mode=incremental {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
|
||||
## Full codegen to cli
|
||||
You can use `--target-mode=core` change the `--azure-cli-extension-folder` to `--azure-cli-folder` to generate cli modules. see [here](how-to-generate-with-different-options.md#generate-cli-main-repo-modules-with-default-option) for more details.
|
||||
You also use other interesting options when generating the cli. see [here](how-to-generate-with-different-options.md#what-kind-of-options-do-we-have) for more details.
|
||||
|
||||
## Incremental codegen to cli
|
||||
Coming soon
|
||||
1. If you are working on **a totally new RP or existing RP but has never been onboarded to Azure CLI before**, I would recommend you to use **Azure CLI Extensions** and use CLI code generator i.e. autorest.az to generate the extension.
|
||||
1. If you are working on **a RP that was onboarded to Azure CLI before in Azure CLI main modules and you have some new operations you would like to add in Azure CLI** and it's better to use Azure CLI main modules and use CLI code generator to incrementally add the new operations.
|
||||
1. If you are working on **a RP that was onboarded to Azure CLI before in either Azure CLI Extensions or Azure CLI main modules but you are okay to replace those manual written code**, it would be better to use our Code Generator to re-generate them all.
|
||||
|
||||
# How to generate code using autorest.az
|
||||
|
||||
## Through PR in [Swagger repo](https://github.com/Azure/azure-rest-api-specs)
|
||||
|
||||
Autorest.az has been integrated into the [swagger repo](https://github.com/Azure/azure-rest-api-specs), which means it will be triggered automatically to generate the CLI code and extension for you without any extra effort as long as the readme files are ready in the swagger repo or PR. To preparing the initial readme file, please following [Preparing Readme](how-to-author-readme-file.md).
|
||||
:warning: This approach is only for CLI extension generation.
|
||||
|
||||
Autorest.az has been integrated into the [swagger repo](https://github.com/Azure/azure-rest-api-specs), which means it will be triggered automatically to generate the CLI extension for you without any extra effort as long as the readme files are ready in the swagger repo or PR. Prepare the initial readme file as documented here in [Preparing Readme](how-to-author-readme-file.md).
|
||||
|
||||
The following is code generation step by step:
|
||||
|
||||
|
|
@ -84,7 +46,7 @@ The following is code generation step by step:
|
|||
|
||||
4. Modify and Merge
|
||||
|
||||
a. If nothing need to be changed after review and try, you can merge the swagger PR. After swagger PR is merged, another PR target to [Az cli extension](https://github.com/Azure/azure-cli-extensions) will be created but marked as closed. Following the link in pipeline, find the PR for Az cli extension, reopen it and ask for code review.
|
||||
a. If nothing needs to be changed after review, merge the swagger PR. After the swagger PR is merged, another PR target to [Az cli extension](https://github.com/Azure/azure-cli-extensions) will be created but marked as closed. Following the link in pipeline, find the PR for Az cli extension, reopen it and ask for code review.
|
||||
|
||||
|
||||
|
||||
|
|
@ -92,9 +54,9 @@ The following is code generation step by step:
|
|||
|
||||
|
||||
|
||||
You can changing the cli code, test and try in local environment with [developing guideline](https://github.com/Azure/azure-cli/blob/dev/doc/configuring_your_machine.md). After completed, please create the Az cli extension PR target to [Az cli extension](https://github.com/Azure/azure-cli-extensions) directly.
|
||||
You can change the cli code and test locally with [developing guideline](https://github.com/Azure/azure-cli/blob/dev/doc/configuring_your_machine.md). After completed, please create the Az cli extension PR target to [Az cli extension](https://github.com/Azure/azure-cli-extensions) directly.
|
||||
|
||||
More detail can also be found in this [10-minutes video](https://msit.microsoftstream.com/video/71cea3ff-0400-a9f4-01b4-f1ea9e9b130e)
|
||||
More detail can also be found in this [video](https://msit.microsoftstream.com/video/71cea3ff-0400-a9f4-01b4-f1ea9e9b130e)
|
||||
|
||||
|
||||
|
||||
|
|
@ -103,26 +65,37 @@ More detail can also be found in this [10-minutes video](https://msit.microsofts
|
|||
We have pre-prepared docker image for you to use autorest.az easily. (Please make sure [Docker](https://www.docker.com/products) has been installed. :))
|
||||
|
||||
1. Start docker:
|
||||
* sync 'https://github.com/Azure/azure-cli-extensions.git' to {azure_cli_ext_folder} and 'https://github.com/Azure/azure-rest-api-specs.git' to {swagger_folder}
|
||||
* sync 'https://github.com/Azure/azure-rest-api-specs.git' to {swagger_folder}
|
||||
* sync 'https://github.com/Azure/azure-cli-extensions.git' to {azure_cli_ext_folder} or 'https://github.com/Azure/azure-cli.git' to {azure_cli_folder}
|
||||
* login to Azure Container Registry and start the docker
|
||||
``` bash
|
||||
> az acr login --name amecodegen
|
||||
if it's for Azure CLI Extensions generation.
|
||||
> docker run -v {swagger_folder}:/home/swg -v {azure_cli_ext_folder}:/home/azext -it amecodegen.azurecr.io/az:2020.05.24 /bin/bash
|
||||
if it's for Azure CLI main modules generation.
|
||||
> docker run -v {swagger_folder}:/home/swg -v {azure_cli_folder}:/home/azcli -it amecodegen.azurecr.io/az:2020.05.24 /bin/bash
|
||||
```
|
||||
|
||||
2. Generate the code:
|
||||
* Make sure the readme files are ready in the swagger repo. We can help to prepare the init readme files for you as mentioned in [onboarding-guide](onboarding-guide.md), or you can also find example [here](../test/scenarios/attestation/configuration).
|
||||
* Generate the code:
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder=/home/azext /home/swg/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
* Generate the code:
|
||||
if it's for Azure CLI Extensions:
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder=/home/azext /home/swg/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
if it's for Azure CLI main repo modules:
|
||||
``` bash
|
||||
> autorest --az --target-mode=core --azure-cli-folder=/home/azcli /home/swg/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
|
||||
3. Run the generated command
|
||||
* Generated commands are ready to use after adding the extension:
|
||||
``` bash
|
||||
> azdev extension add {service_name}
|
||||
# your command is ready to use now
|
||||
```
|
||||
* Generated commands are ready to use after adding the extension:
|
||||
If it's for Azure CLI Extensions.
|
||||
``` bash
|
||||
> azdev extension add {service_name}
|
||||
# your command is ready to use now
|
||||
```
|
||||
If it's for Azure CLI main repo modules, then there's nothing more needed.
|
||||
|
||||
4. Run generated test cases and style check
|
||||
* run azdev test
|
||||
|
|
@ -142,15 +115,22 @@ We have pre-prepared docker image for you to use autorest.az easily. (Please mak
|
|||
|
||||
## Through autorest command directly in local
|
||||
1. Make sure your environment is good to run autorest and autorest.python by following [this](https://github.com/Azure/autorest.python/wiki/Generating-with-autorest-for-python-v5.0.0).
|
||||
2. sync 'https://github.com/Azure/azure-cli-extensions.git' to {azure_cli_ext_folder} and 'https://github.com/Azure/azure-rest-api-specs.git' to {swagger_folder}
|
||||
3. Generate the code:
|
||||
* Make sure the readme files are ready in the swagger repo. To preparing the initial readme file, please following [Preparing Readme](how-to-author-readme-file.md).
|
||||
* Generate the code:
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder={azure_cli_ext_folder} {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
1. sync 'https://github.com/Azure/azure-rest-api-specs.git' to {swagger_folder}
|
||||
1. sync 'https://github.com/Azure/azure-cli-extensions.git' to {azure_cli_ext_folder} or 'https://github.com/Azure/azure-cli.git' to {azure_cli_folder} if you are working on Azure CLI main modules generation.
|
||||
1. Generate the code:
|
||||
* Make sure the readme files are ready in the swagger repo. To prepare the initial readme file, please following [Preparing Readme](how-to-author-readme-file.md).
|
||||
* Generate the code:
|
||||
if it's for Azure CLI Extensions generation:
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder={azure_cli_ext_folder} {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
if it's for Azure CLI main modules generation:
|
||||
``` bash
|
||||
> autorest --az --target-mode=core --azure-cli-folder={azure_cli_folder} {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
|
||||
3. Run the generated command
|
||||
1. Run the generated command
|
||||
:warning: This step is only needed for Azure CLI Extensions generation.
|
||||
* Build az extension from the generated code and load it in az
|
||||
``` bash
|
||||
# run this in the folder with generated code: {azure_cli_ext_folder}/src/{service_name}
|
||||
|
|
@ -158,8 +138,41 @@ We have pre-prepared docker image for you to use autorest.az easily. (Please mak
|
|||
> az extension add --source={azure_cli_ext_folder}/src/{service_name}/dist/{generated .whl file}
|
||||
# your az command is ready to use :)
|
||||
```
|
||||
4. Run the generated test
|
||||
1. Run the generated test
|
||||
* Follow the [guidance](https://github.com/Azure/azure-cli/blob/dev/doc/authoring_tests.md) from azure-cli for running test.
|
||||
|
||||
5. Run linter and style check
|
||||
* Follow the [guidance](https://github.com/Azure/azure-cli/blob/dev/doc/configuring_your_machine.md#running-tests-and-checking-code-style) to run linter and style check.
|
||||
1. Run linter and style check
|
||||
* Follow the [guidance](https://github.com/Azure/azure-cli/blob/dev/doc/configuring_your_machine.md#running-tests-and-checking-code-style) to run linter and style check.
|
||||
|
||||
|
||||
## Full and Incremental.
|
||||
In both Azure CLI main modules or Azure CLI Extensions generation, CLI Code Generator also supports two generation mode: full and incremental.
|
||||
|
||||
* Full: generates all the operations/apis defined in the input rest api specs for that RP.
|
||||
* Incremental: generates several specific operations that you have configured in readme files.
|
||||
|
||||
In incremental generation, we will put our generated code into a generated folder in your modules code folder and the only change for existing code is to add import logic in very few places so that the code in generated folder can be loaded by CLI commands loader.
|
||||
|
||||
### Incremental codegen configuration:
|
||||
1. Readme: Besides following [Preparing Readme](how-to-author-readme-file.md). Incremental mode needs to be configured in the Readme.az.md file. There are two ways to configure incremental mode:
|
||||
* **Allow list** hide all commands by setting hidden to true. Then unhide the command groups or commands to be generated:
|
||||
|
||||
|
||||
* **Deny list** make all commands visible and hide the command groups or commands to not be generated:
|
||||
|
||||
|
||||
|
||||
2. As autorest.az supports auto detect full/incremental generation mode:
|
||||
* If the cli extention folder for target RP is empty or the code was generated by autorest.az before, then full code generation mode will be run.
|
||||
* If the cli extention folder for target RP is not empty and the code was manually written before, incremental code generation mode will be run.
|
||||
|
||||
Normally you don't need to care about the generation mode, because the code generator will automatically add the import logic if it found code already exists. and what operations will be generated is determined by the Readme **allow list** or **deny list**
|
||||
|
||||
But you can still add `--generation-mode=full` or `--generation-mode=incremental` to force full/incremental code generation during both Azure CLI main modules generation or Azure CLI extension generation:
|
||||
``` bash
|
||||
> autorest --az --azure-cli-extension-folder={azure_cli_ext_folder} --generation-mode=full {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
or
|
||||
``` bash
|
||||
> autorest --az --target-mode=core --azure-cli-folder={azure_cli_folder} --generation-mode=incremental {swagger_folder}/specification/{service_name}/resource-manager/readme.md
|
||||
```
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче