From 36b7276ac9ff8895aa5e1b5bdbc01f41f935b4e7 Mon Sep 17 00:00:00 2001 From: Qiaoqiao Zhang <55688292+qiaozha@users.noreply.github.com> Date: Tue, 28 Jul 2020 12:53:04 +0800 Subject: [PATCH] add doc for typescript md (#10187) * add doc for typescript md * add description of tag * change the description --- .../code-gen/configure-typescript-sdk.md | 235 ++++++++++++++++++ 1 file changed, 235 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 00000000000..881578aa402 --- /dev/null +++ b/documentation/code-gen/configure-typescript-sdk.md @@ -0,0 +1,235 @@ +# 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. + +### 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-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 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, +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 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. + +~~~ +## 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 +~~~