add doc for typescript md (#10187)
* add doc for typescript md * add description of tag * change the description
This commit is contained in:
Qiaoqiao Zhang
GitHub
Родитель
cc6727f0ef
Коммит
36b7276ac9
|
|
@ -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=<path to root folder of your azure-sdk-for-js clone>`.
|
||||
|
||||
``` 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=<path to root folder of your azure-sdk-for-js clone>`.
|
||||
|
||||
```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
|
||||
~~~
|
||||
Загрузка…
Ссылка в новой задаче