From b3aea27d19649eb747fa074337fe136dafc31daa Mon Sep 17 00:00:00 2001 From: qiaozha Date: Fri, 17 Jul 2020 14:28:02 +0800 Subject: [PATCH 1/3] add doc for typescript md --- .../code-gen/configure-typescript-sdk.md | 224 ++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 documentation/code-gen/configure-typescript-sdk.md diff --git a/documentation/code-gen/configure-typescript-sdk.md b/documentation/code-gen/configure-typescript-sdk.md new file mode 100644 index 000000000000..42898e374dc2 --- /dev/null +++ b/documentation/code-gen/configure-typescript-sdk.md @@ -0,0 +1,224 @@ +# Readme Configuration Guide for Typescript SDK +This file describe how to configure readme files to make it available for Typescript SDK code generation. + +## Common Configuration +Configure basic package information. + +### 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 +A tag can contains a bunch of swagger files which are used to generate the SDK. For Example: + +~~~~ +// file: readme.md + + +### Tag: package-2020-05-01 + +These settings apply only when `--tag=package-2020-05-01` is specified on the command line. + +``` yaml $(tag) == 'package-2020-05-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 Typescript SDK 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-sdk-for-js + - ... + + +## Typescript + +See configuration in [readme.typescript.md](./readme.typescript.md) +~~~ + +## Typescript Configuration +Typescript dedicated configurations are configured in readme.typescript.md. +the typical package-name is usually like `@azure/arm-xxx` where the xxx is related with the service name. +and the typical output-folder in the azure-sdk-for-js is like `$(typescript-sdks-folder)/sdk/xxx/arm-xxx` where the xxx is related with the service name. +A typical readme.typescript.md is like this: +~~~ +// file: readme.typescript.md + +## TypeScript + +These settings apply only when `--typescript` is specified on the command line. +Please also specify `--typescript-sdks-folder=`. + +``` yaml $(typescript) +typescript: + azure-arm: true + package-name: "@azure/arm-apimanagement" + output-folder: "$(typescript-sdks-folder)/sdk/apimanagement/arm-apimanagement" + clear-output-folder: true + generate-metadata: true +``` + +~~~ + +## Multi-api +Currently the Typescript SDK doesn't support multi-api which means each operation contained in one package should only contains one api-version's. and Typescript SDK only supports single api package. + +## Multi-packages +The batch is a tag list which are used in the one RP has multi-package scenarios. For example, +the Resources RP has several independent packages like features, lock, policy. +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-features) +tag: package-features-2015-12 +``` + +``` yaml $(package-locks) +tag: package-locks-2016-09 +``` + +``` yaml $(package-policy) +tag: package-policy-2019-09 +``` + +``` yaml $(package-resources) +tag: package-resources-2020-06 +``` + +~~~ +Then for each default tag, you can define the input swagger like normal tag. +~~~ + +### Tag: package-features-2015-12 + +These settings apply only when `--tag=package-features-2015-12` is specified on the command line. + +``` yaml $(tag) == 'package-features-2015-12' +input-file: +- Microsoft.Features/stable/2015-12-01/features.json +``` + +### Tag: package-locks-2016-09 + +These settings apply only when `--tag=package-locks-2016-09` is specified on the command line. + +``` yaml $(tag) == 'package-locks-2016-09' +input-file: +- Microsoft.Authorization/stable/2016-09-01/locks.json +``` + +### Tag: package-policy-2019-09 + +These settings apply only when `--tag=package-policy-2019-09` is specified on the command line. + +``` yaml $(tag) == 'package-policy-2019-09' +input-file: +- Microsoft.Authorization/stable/2019-09-01/policyAssignments.json +- Microsoft.Authorization/stable/2019-09-01/policyDefinitions.json +- Microsoft.Authorization/stable/2019-09-01/policySetDefinitions.json + +# Needed when there is more than one input file +override-info: + title: PolicyClient +``` + +### Tag: package-resources-2020-06 + +These settings apply only when `--tag=package-resources-2020-06` is specified on the command line. + +``` yaml $(tag) == 'package-resources-2020-06' +input-file: +- Microsoft.Resources/stable/2020-06-01/resources.json +``` +~~~ + +Finally, in your readme.typescript.md you should include what packages you want to include in the Typescript SDK. +And in each package's section define the default package name output folder in azure-sdk-for-js repo etc. + +~~~ +## TypeScript + +These settings apply only when `--typescript` is specified on the command line. +Please also specify `--typescript-sdks-folder=`. + +```yaml $(typescript) && !$(profile) +typescript: + azure-arm: true + batch: true + generate-metadata: true +batch: + - package-features: true + - package-locks: true + - package-policy: true + - package-resources: true +``` + +```yaml $(typescript) && $(package-features) && !$(profile) +typescript: + package-name: "@azure/arm-features" + output-folder: "$(typescript-sdks-folder)/sdk/features/arm-features" + clear-output-folder: true +``` + +```yaml $(typescript) && $(package-locks) && !$(profile) +typescript: + package-name: "@azure/arm-locks" + output-folder: "$(typescript-sdks-folder)/sdk/locks/arm-locks" + clear-output-folder: true +``` + +```yaml $(typescript) && $(package-policy) && !$(profile) +typescript: + package-name: "@azure/arm-policy" + output-folder: "$(typescript-sdks-folder)/sdk/policy/arm-policy" + clear-output-folder: true +``` + +```yaml $(typescript) && $(package-resources) && !$(profile) +typescript: + package-name: "@azure/arm-resources" + output-folder: "$(typescript-sdks-folder)/sdk/resources/arm-resources" + clear-output-folder: true +``` + +~~~ + + +## Run codegen +After configure all the readme files, autorest can be used to generate SDK. +~~~ +autorest --typescript --typescript-sdks-folder=/home/qiaozha/code/azure-sdk-for-js --license-header=MICROSOFT_MIT_NO_VERSION /home/qiaozha/code/azure-rest-api-specs/specification/storage/resource-manager/readme.md --use=@microsoft.azure/autorest.typescript@4.2.2 +~~~ From 185da21b95942ce0eac47f4e3ce31351fa4c9aa2 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Mon, 27 Jul 2020 16:27:22 +0800 Subject: [PATCH 2/3] add description of tag --- .../code-gen/configure-typescript-sdk.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/documentation/code-gen/configure-typescript-sdk.md b/documentation/code-gen/configure-typescript-sdk.md index 42898e374dc2..e7a9ca7dc5f7 100644 --- a/documentation/code-gen/configure-typescript-sdk.md +++ b/documentation/code-gen/configure-typescript-sdk.md @@ -18,17 +18,28 @@ tag: package-xxxx-xx-xx ~~~~ ### tag -A tag can contains a bunch of swagger files which are used to generate the SDK. For Example: +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-2020-05-01 +### Tag: package-2019-12-01 -These settings apply only when `--tag=package-2020-05-01` is specified on the command line. +These settings apply only when `--tag=package-2019-12-01` is specified on the command line. -``` yaml $(tag) == 'package-2020-05-01' +``` yaml $(tag) == 'package-2019-12-01' input-file: - Microsoft.Compute/stable/2019-12-01/compute.json - Microsoft.Compute/stable/2019-12-01/runCommands.json From aa714be10d8797c939ac33afd6ad9115cbfe480d Mon Sep 17 00:00:00 2001 From: qiaozha Date: Tue, 28 Jul 2020 12:29:41 +0800 Subject: [PATCH 3/3] change the description --- documentation/code-gen/configure-typescript-sdk.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/code-gen/configure-typescript-sdk.md b/documentation/code-gen/configure-typescript-sdk.md index e7a9ca7dc5f7..881578aa402f 100644 --- a/documentation/code-gen/configure-typescript-sdk.md +++ b/documentation/code-gen/configure-typescript-sdk.md @@ -1,5 +1,5 @@ -# Readme Configuration Guide for Typescript SDK -This file describe how to configure readme files to make it available for Typescript SDK code generation. +# Readme Configuration Guide for Azure SDK for Javascript (Typescript) +This file describe how to configure readme files to make it available for Azure SDK for Javascript (Typescript) code generation. ## Common Configuration Configure basic package information. @@ -49,7 +49,7 @@ input-file: ## Swagger to SDK -To make Typescript SDK can be generated from the tag, swagger-to-sdk need to be configured: +To make Azure SDK for Javascript (Typescript) can be generated from the tag, swagger-to-sdk need to be configured: ~~~ // file: readme.md @@ -95,7 +95,7 @@ typescript: ~~~ ## Multi-api -Currently the Typescript SDK doesn't support multi-api which means each operation contained in one package should only contains one api-version's. and Typescript SDK only supports single api package. +Currently the Azure SDK for Javascript (Typescript) doesn't support multi-api which means each operation contained in one package should only contains one api-version's. and Azure SDK for Javascript (Typescript) only supports single api package. ## Multi-packages The batch is a tag list which are used in the one RP has multi-package scenarios. For example, @@ -176,7 +176,7 @@ input-file: ``` ~~~ -Finally, in your readme.typescript.md you should include what packages you want to include in the Typescript SDK. +Finally, in your readme.typescript.md you should include what packages you want to include in the Azure SDK for Javascript (Typescript). And in each package's section define the default package name output folder in azure-sdk-for-js repo etc. ~~~