Update dpg+rlc getStarted doc (#23848)
* Update dpg+rlc getStarted doc * Update the doc to enable generte-sample by default * Update according to relevant comments * Update small format issue * Small fix * Update swagger one * Update sample generation and test cases * Update non-block process with sample failure * Add format * Update title * Update RLC-quickstart.md * Update RLC-quickstart.md * Update lint command * Update documentation/RLC-quickstart.md Co-authored-by: Qiaoqiao Zhang <55688292+qiaozha@users.noreply.github.com> * Update documentation/RLC-quickstart.md Co-authored-by: Qiaoqiao Zhang <55688292+qiaozha@users.noreply.github.com> * Update documentation/RLC-quickstart.md Co-authored-by: Qiaoqiao Zhang <55688292+qiaozha@users.noreply.github.com> * Update according to comments * Resolve comments * Remove useless codes * Update spaces * Fix small issues * Update filename * update broken links * Update wordings * Wording change Co-authored-by: Qiaoqiao Zhang <55688292+qiaozha@users.noreply.github.com>
This commit is contained in:
Mary Gao
GitHub
Родитель
81d5c306e2
Коммит
83f2b9b204
|
|
@ -15,8 +15,8 @@ This page is to help you write and run tests quickly for Javascript Codegen SDK
|
|||
- [Client authentication](#client-authentication)
|
||||
- [AzureAD OAuth2 Authentication](#azuread-oauth2-authentication)
|
||||
- [API Key Authentication](#api-key-authentication)
|
||||
- [Example 1: Basic Azure data-plane service interaction and recording](#example-1-basic-azure-data-plane-service-interaction-and-recording)
|
||||
- [Example 2: Basic Azure management service interaction and recording](#example-2-basic-azure-management-service-interaction-and-recording)
|
||||
- [Example 1: Basic RLC test interaction and recording for Azure data-plane service](#example-1-basic-rlc-test-interaction-and-recording-for-azure-data-plane-service)
|
||||
- [Example 2: Basic HLC test interaction and recording for Azure management service](#example-2-basic-hlc-test-interaction-and-recording-for-azure-management-service)
|
||||
|
||||
# Background
|
||||
|
||||
|
|
@ -199,7 +199,7 @@ await recorder.start(recorderEnvSetup);
|
|||
|
||||
API key authentication would hit the service's endpoint directly so these traffic will be recorded. It doesn't require any customization in tests. However we must secure the sensitive data and not leak into our recordings, so add a sanitizer to replace your API keys. You could read more on how to add sanitizer at [here](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/test-utils/recorder/README.md).
|
||||
|
||||
## Example 1: Basic Azure data-plane service interaction and recording
|
||||
## Example 1: Basic RLC test interaction and recording for Azure data-plane service
|
||||
|
||||
At the code structure [section](#code-structure) we described we'll generate sample file for you, if you are the first time to write test cases you could grow up your own based on them.
|
||||
|
||||
|
|
@ -242,7 +242,7 @@ describe("My test", () => {
|
|||
// Step 1: Create your test case
|
||||
it("Should create a glossary", async () => {
|
||||
// Step 3: Add your test cases
|
||||
const glossary = await client.path("/atlas/v2/glossary").post({
|
||||
const glossaryResponse = await client.path("/atlas/v2/glossary").post({
|
||||
body: {
|
||||
name: glossaryName,
|
||||
shortDescription: "Example Short Description",
|
||||
|
|
@ -251,8 +251,11 @@ describe("My test", () => {
|
|||
usage: "Example Glossary",
|
||||
},
|
||||
});
|
||||
if (isUnexpected(glossaryResponse)) {
|
||||
throw new Error(glossaryResponse.body?.error.message);
|
||||
}
|
||||
// Step 5: Add your assertions
|
||||
assert.strictEqual(glossary.status, "200");
|
||||
assert.strictEqual(glossaryResponse.status, "200");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
|
@ -300,7 +303,7 @@ export function createClient(recorder: Recorder, options?: ClientOptions): Purvi
|
|||
}
|
||||
```
|
||||
|
||||
## Example 2: Basic Azure management service interaction and recording
|
||||
## Example 2: Basic HLC test interaction and recording for Azure management service
|
||||
|
||||
At the code structure [section](#code-structure) we described if your SDK is generated base on HLC we'll generate a sample test named `sampleTest.ts` for you.
|
||||
|
||||
|
|
@ -0,0 +1,299 @@
|
|||
Getting Started - Generate the RLC rest-level client libraries with Swagger
|
||||
===========================================================================
|
||||
|
||||
# Before you start
|
||||
|
||||
Please refer to this [link](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md#prerequisites) for the environment set up prerequisites in azure-sdk-for-js repository. We highly recommand to read [this blog](https://devblogs.microsoft.com/azure-sdk/azure-rest-libraries-for-javascript/) to get familiar with REST libraries for JavaScript.
|
||||
|
||||
|
||||
# Project folder and name convention
|
||||
|
||||
If you are the first time to prepare the SDK, please follow the Azure SDK guidance and discuss with architects to decide the project folder and name convention for RLC libraries.
|
||||
|
||||
1. Project Folder structure.
|
||||
normally, the folder structure would be something like `sdk/{servicename}/{servicename}-{modulename}-rest`. For example, we have `sdk/agrifood/agrifood-farming-rest` folder for Farmbeats account modules. That folder will be your **${PROJECT_ROOT} folder**.
|
||||
1. Package Name Convention.
|
||||
The package name for RLC is something like `@azure-rest/{servicename}-{modulename}`. For example, the package name for Farmbeats module is `@azure-rest/agrifood-farming`.
|
||||
|
||||
# How to generate RLC
|
||||
|
||||
We are working on to automatically generate everything right now, but currently we still need some manual work to get a releasable package. Here're the steps of how to get the package.
|
||||
|
||||
1. **Create a swagger/README.md file.under ${PROJECT_ROOT} folder**
|
||||
We are using autorest to generate the code, but there's a lot of command options and in order to make the regenerate process easier in the cases of refresh the rest api input or change the code generator version, you need to document the generate command parameters.
|
||||
Here's an example of the swagger/README.md
|
||||
|
||||
~~~
|
||||
|
||||
# Azure Farmbeats TypeScript Protocol Layer
|
||||
|
||||
> see https://aka.ms/autorest
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
package-name: "@azure-rest/agrifood-farming"
|
||||
title: Farmbeats
|
||||
description: Farmbeats Client
|
||||
generate-metadata: true
|
||||
generate-test: true
|
||||
generate-sample: true
|
||||
license-header: MICROSOFT_MIT_NO_VERSION
|
||||
output-folder: ../
|
||||
source-code-folder-path: ./src
|
||||
input-file: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/683e3f4849ee1d84629d0d0fa17789e80a9cee08/specification/agfood/data-plane/Microsoft.AgFoodPlatform/preview/2021-03-31-preview/agfood.json
|
||||
package-version: 1.0.0-beta.2
|
||||
rest-level-client: true
|
||||
security: AADToken
|
||||
security-scopes: https://farmbeats.azure.net/.default
|
||||
use-extension:
|
||||
"@autorest/typescript": "6.0.0-rc.1"
|
||||
```
|
||||
~~~
|
||||
|
||||
Here, we need to replace the value in `package-name`, `title`, `description`, `input-file`, `package-version`, `security`,`security-scopes` into **your own service's** `package-name`, `title`, `description` etc.
|
||||
|
||||
**How to configure authentication**
|
||||
|
||||
Autorest only support two types of authentication: Azure Key Credential(AzureKey) and Token credential(AADToken), any other will need to be handled manually.
|
||||
|
||||
This could be either configured in OpenAPI spec or configuration file e.g `README.md`. You could learn more in [Authentication in AutoRest](https://github.com/Azure/autorest/blob/main/docs/generate/authentication.md).
|
||||
|
||||
Here are the details if we configure in README.md file.
|
||||
- Support AAD token authentication
|
||||
```yaml
|
||||
security: AzureKey
|
||||
security-header-name: Your-Subscription-Key
|
||||
```
|
||||
- Support key authentication
|
||||
```yaml
|
||||
security: AADToken
|
||||
security-scopes: https://yourendpoint.azure.com/.default
|
||||
```
|
||||
- Support both credentials
|
||||
```yaml
|
||||
security:
|
||||
- AADToken
|
||||
- AzureKey
|
||||
security-header-name: Your-Subscription-Key
|
||||
security-scopes: https://yourendpoint.azure.com/.default
|
||||
```
|
||||
- Disable neither authentications
|
||||
```yaml
|
||||
add-credentials: false
|
||||
```
|
||||
|
||||
---
|
||||
**NOTE**
|
||||
|
||||
It's always recommended to replace the version of code generator @autorest/typescript with the latest version you can find in [npmjs.com](https://www.npmjs.com/package/@autorest/typescript) in latest tag.
|
||||
|
||||
If the `input-file` is followed by an `. md` file, you need to replace the `input-file` with `require`. If it is a `JSON` file, do not change it.
|
||||
|
||||
We enable the samples generation by default, this may fail the generation due to the example quality or codegen issue. You could turn this option off by `generate-sample: false` to non-block your process.
|
||||
|
||||
**After the first generation, you need to switch `generate-metadata: false` as we have some manual changes in this file and don't want them get overwrite by generated ones.**
|
||||
|
||||
---
|
||||
|
||||
1. **Edit rush.json**
|
||||
As the libraries in this azure-sdk-for-js repository are managed by rush, you need to add an entry in rush.json under projects section for the first time to make sure it works. For example:
|
||||
|
||||
```
|
||||
{
|
||||
"packageName": "@azure-rest/agrifood-farming",
|
||||
"projectFolder": "sdk/agrifood/agrifood-farming-rest",
|
||||
"versionPolicyName": "client"
|
||||
},
|
||||
```
|
||||
|
||||
Here you also need to replace the `packageName`, `projectFolder` into your own services'.
|
||||
|
||||
---
|
||||
**NOTE**
|
||||
|
||||
About the `versionPolicyName`, if the library you are working on is for data-plane, then it should be `client`, if the library you are working on is for control plane, then it should be `mgmt`.
|
||||
|
||||
---
|
||||
|
||||
1. **Run autorest to generate the SDK**
|
||||
|
||||
Now you can run this command in swagger folder you just created.
|
||||
|
||||
```shell
|
||||
autorest --typescript ./README.md
|
||||
```
|
||||
|
||||
After this finishes, you will see the generated code in `${PROJECT_ROOT}/src` folder.
|
||||
After that, you can get a workable package, and run the following commands to get a artifact if you like.
|
||||
|
||||
```shell
|
||||
rush update
|
||||
rush build -t <your-package-name>
|
||||
cd <your-sdk-folder>
|
||||
rushx pack
|
||||
```
|
||||
|
||||
But we still need to add some tests for it.
|
||||
|
||||
# Improve README.md document
|
||||
|
||||
A minimal README.md is generated by our codegen and you could improve it with more meaningful information.
|
||||
|
||||
|
||||
# How to write test for RLC
|
||||
|
||||
In order to release it, we need to add some tests for it to make sure we are delivering high quality packages. But before we add the test, we need to add a `generate-test: true` make the codegen generate the necessary change in `package.json` and `tsconfig.json` so that test framework can work. Once the generation finished, you will see a `sampleTest.spec.ts` file in your `{PROJECT_ROOT}/test/public` folder, which only has an empty test and you may change them into test against your own services.
|
||||
|
||||
See the [Javascript Codegen Quick Start for Test](./Quickstart-on-how-to-write-tests.md) for information on how to write and run tests for the Javascript SDK.
|
||||
|
||||
1. **Prerequisites**
|
||||
|
||||
To record and playback the tests, [Docker](https://www.docker.com/) is required when we run the test, as the [test proxy server](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy) is run in a container during testing. When running the tests, ensure the Docker daemon is running and you have permission to use it.
|
||||
|
||||
1. **Write the test**
|
||||
|
||||
You could follow the [basic RLC test interaction and recording example](./Quickstart-on-how-to-write-tests.md#example-1-basic-rlc-test-interaction-and-recording-for-azure-data-plane-service) to write your own test step by step.
|
||||
|
||||
1. **Run the test**
|
||||
Now, you can run the test like this. If you are the first time to run test, you need to set the environment variable `TEST_MODE` to `record`. This will generate recordings for your test they could be used in `playback` mode.
|
||||
On Linux, you could use `export` to set env variable:
|
||||
```shell
|
||||
rush build -t ${PACKAGE_NAME}
|
||||
export TEST_MODE=record && rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
|
||||
```
|
||||
On Windows, you could use `SET`:
|
||||
```shell
|
||||
rush build -t ${PACKAGE_NAME}
|
||||
SET TEST_MODE=record&& rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
|
||||
```
|
||||
You can also run the `playback` mode test if your apis don't have breaking changes and you've already done the recording before.
|
||||
On Linux, you could use below commands:
|
||||
```shell
|
||||
rush build -t ${PACKAGE_NAME}
|
||||
export TEST_MODE=playback && rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
|
||||
```
|
||||
On Windows, you can use:
|
||||
```shell
|
||||
rush build -t ${PACKAGE_NAME}
|
||||
SET TEST_MODE=playback&& rushx test # this will run live test and generate a recordings folder, you will need to submit it in the PR.
|
||||
```
|
||||
|
||||
|
||||
# How to write samples
|
||||
|
||||
If you enable `generate-sample: true` option the codegen would do two things for you:
|
||||
- Add samples metadata in `tsconfig.json` and `package.json`
|
||||
- Generate a collection of Typescript sample files (based on x-ms-examples in OpenAPI specs) under `samples-dev` folder.
|
||||
|
||||
Please notice that the generated samples might not be directly usable as runnable codes, however we could get the basic idea on how code works, and update them to be more valuable samples.
|
||||
|
||||
And the errors may come from two kinds, the codegen issue or swagger example issue. For the former one we need to report them with codegen owner while as for the latter one we need to fix our swagger examples.
|
||||
|
||||
Now, you can generate both JavaScript and TypeScript workable samples with the following commands.
|
||||
```shell
|
||||
npm install -g common/tools/dev-tool # make sure you are in the azure-sdk-for-js repo root directory
|
||||
cd ${PROJECT_ROOT}
|
||||
npx dev-tool samples publish -f
|
||||
```
|
||||
You will see the workable samples in the `${PROJECT_ROOT}/samples` folder.
|
||||
|
||||
# Format both the generated code and manual code
|
||||
After you have finished the generation and added your own tests or samples, You can use the following command to format the code.
|
||||
```shell
|
||||
cd ${PROJECT_ROOT} && rushx format
|
||||
```
|
||||
|
||||
Also we'll recommand you to run `lint` command to analyze your code and quickly find any problems.
|
||||
|
||||
```shell
|
||||
cd ${PROJECT_ROOT} && rushx lint
|
||||
```
|
||||
|
||||
And we could use `lint:fix` if there are any errors.
|
||||
|
||||
```shell
|
||||
cd ${PROJECT_ROOT} && rushx lint:fix
|
||||
```
|
||||
|
||||
# How to create package
|
||||
|
||||
Now we can use the exact same steps to build an releasable artifact.
|
||||
|
||||
```shell
|
||||
rush update
|
||||
rush build -t <your-package-name>
|
||||
cd <your-sdk-folder>
|
||||
export TEST_MODE=record && rushx test
|
||||
rushx pack
|
||||
```
|
||||
You may send this artifact to your customer if your services are still in private preview and some customers want to try it out.
|
||||
# Create/Update the ci.yaml
|
||||
|
||||
Now, if everything looks good to you, you can submit a PR in azure-sdk-for-js repo with all the changes you made above. Before you do that, you need to add/update the ci.yml file. Depends on whether there's already one in your package folder.
|
||||
|
||||
If there's no such file then you can add the following template.
|
||||
|
||||
``` yaml
|
||||
# NOTE: Please refer to https://aka.ms/azsdk/engsys/ci-yaml before editing this file.
|
||||
trigger:
|
||||
branches:
|
||||
include:
|
||||
- main
|
||||
- release/*
|
||||
- hotfix/*
|
||||
paths:
|
||||
include:
|
||||
- sdk/purview/
|
||||
pr:
|
||||
branches:
|
||||
include:
|
||||
- main
|
||||
- feature/*
|
||||
- release/*
|
||||
- hotfix/*
|
||||
exclude:
|
||||
- feature/v4
|
||||
paths:
|
||||
include:
|
||||
- sdk/purview/
|
||||
extends:
|
||||
template: ../../eng/pipelines/templates/stages/archetype-sdk-client.yml
|
||||
parameters:
|
||||
ServiceDirectory: purview
|
||||
Artifacts:
|
||||
- name: azure-rest-agrifood-farming
|
||||
safeName: azurerestagrifoodfarming
|
||||
```
|
||||
|
||||
Please change the paths.include value as your own project path, and change the Artifacts name and safeName into yours.
|
||||
|
||||
If there's already a ci.yml file in your project path. then the only thing you need to do is to add the Artifacts name and safeName of yours into that ci.yml.
|
||||
|
||||
Please notice the Artifacts name should align with your package name. Here the package name is `@azure-rest/agrifood-farming` so the relevant Artifacts name is `azure-rest-agrifood-farming`.
|
||||
|
||||
|
||||
# Prepare PR
|
||||
|
||||
The codegen can only help you generate SDK code, there is something you need to update manually:
|
||||
|
||||
## CHANGELOG.md
|
||||
|
||||
CHANGELOG can help customers know the change of new version quicky, so you need to update the it according to the change of this new version. It is also necessary to update release date like `1.0.0-beta.1 (2022-11-11)`(rough time is fine and no need to be very accurate).
|
||||
|
||||
## Version Number
|
||||
|
||||
You shall update the version number according to [semantic versioning rule](https://semver.org/).
|
||||
|
||||
## Test recordings
|
||||
|
||||
Please ensure that your test recordings are committed together with your code.
|
||||
|
||||
## Fix CI for PR
|
||||
You may meet the CI failures after submitting the PR, so please refer to [Troubleshoot CI Failure](./Troubleshoot-ci-failure.md) to fix it.
|
||||
|
||||
# Create API View
|
||||
When submitting a PR our pipeline would automatically prepare the API view in [API View Website](https://apiview.dev/). You could see an [example link](https://github.com/Azure/azure-sdk-for-js/pull/23866#issuecomment-1316259448) here. You could click the API view link in that comment to know more details.
|
||||
|
||||
# Release
|
||||
|
||||
After the PR is merged, it is time to release package. Here is the [Release Checklist](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/8/Release-Checklist?anchor=prepare-release-script) you should know before release.
|
||||
|
|
@ -1,68 +1,75 @@
|
|||
Getting Started - Generate the RLC rest-level client libraries
|
||||
================================================================
|
||||
Getting Started - Generate the RLC rest-level client libraries with Cadl
|
||||
========================================================================
|
||||
|
||||
# Prerequisites
|
||||
# Before you start
|
||||
|
||||
You may refer to this [link](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md#prerequisites) for the environment set up prerequisites in azure-sdk-for-js repository.
|
||||
Please refer to this [link](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md#prerequisites) for the environment set up prerequisites in azure-sdk-for-js repository. We highly recommand to read [this blog](https://devblogs.microsoft.com/azure-sdk/azure-rest-libraries-for-javascript/) to get familiar with REST libraries for JavaScript.
|
||||
|
||||
# Project folder and name convention
|
||||
:warning: Note: if you’re still generating from Swagger with RLC, please read [this doc](./RLC-Swagger-quickstart.md) for Swagger specific details.
|
||||
|
||||
Before we start, we probably should get to know the project folder and name convention for RLC libraries.
|
||||
|
||||
1. Project Folder structure.
|
||||
normally, the folder structure would be something like `sdk/{servicename}/{servicename}-{modulename}-rest`. For example, we have `sdk/agrifood/agrifood-farming-rest` folder for Farmbeats account modules. That folder will be your **${PROJECT_ROOT} folder**.
|
||||
# Project folder structure and name convention
|
||||
|
||||
If you are the first time to prepare the SDK, please follow the Azure SDK guidance and discuss with architects to decide the project folder and name convention for RLC libraries.
|
||||
|
||||
1. SDK Repo Root.
|
||||
The generated libraries should be in the [azure-sdk-for-js](https://github.com/Azure/azure-sdk-for-js) repo, so fork and clone it in your local then the absolute path is called **${SDK_REPO_ROOT} folder**.
|
||||
|
||||
1. Project Folder Structure.
|
||||
Normally, the folder structure would be something like `sdk/{servicename}/{servicename}-{modulename}-rest`. For example, we have `sdk/agrifood/agrifood-farming-rest` folder for Farmbeats account modules under {SDK_REPO_ROOT}. That folder will be your **${PROJECT_ROOT} folder**.
|
||||
1. Package Name Convention.
|
||||
The package name for RLC is something like `@azure-rest/{servicename}-{modulename}`. For example, the package name for Farmbeats module is `@azure-rest/agrifood-farming`.
|
||||
|
||||
|
||||
# How to generate RLC
|
||||
|
||||
We are working on to automatically generate everything right now, but currently we still need some manual work to get a releasable package. Here're the steps of how to get the package.
|
||||
|
||||
1. **Create a swagger/README.md file.under ${PROJECT_ROOT} folder**
|
||||
We are using autorest to generate the code, but there's a lot of command options and in order to make the regenerate process easier in the cases of refresh the rest api input or change the code generator version, you need to document the generate command parameters.
|
||||
Here's an example of the swagger/README.md
|
||||
1. **Add Typescript emitter dependency in package.json**
|
||||
|
||||
In Cadl project, modify `package.json` to add dependency for Typescript emitter, then run `npm install` again to install `@azure-tools/cadl-typescript`.
|
||||
|
||||
~~~
|
||||
|
||||
# Azure Farmbeats TypeScript Protocol Layer
|
||||
|
||||
> see https://aka.ms/autorest
|
||||
## Configuration
|
||||
```json
|
||||
"dependencies": {
|
||||
...
|
||||
"@azure-tools/cadl-typescript": "1.0.0-beta.4"
|
||||
},
|
||||
```
|
||||
|
||||
---
|
||||
**NOTE**
|
||||
|
||||
It's always recommended to replace the version of emitter cadl-typescript with the latest version you can find in [npmjs.com](https://www.npmjs.com/package/@azure-tools/cadl-typescript) in latest tag.
|
||||
|
||||
---
|
||||
|
||||
1. **Configure Typescript emitter in cadl-project.yaml**
|
||||
|
||||
In Cadl project, modify (or create) `cadl-project.yaml` and configure the SDK generated, using the emitter options on `@azure-tools/cadl-typescript`
|
||||
|
||||
```yaml
|
||||
package-name: "@azure-rest/agrifood-farming"
|
||||
title: Farmbeats
|
||||
description: Farmbeats Client
|
||||
generate-metadata: true
|
||||
generate-test: true
|
||||
license-header: MICROSOFT_MIT_NO_VERSION
|
||||
output-folder: ../
|
||||
source-code-folder-path: ./src
|
||||
input-file: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/683e3f4849ee1d84629d0d0fa17789e80a9cee08/specification/agfood/data-plane/Microsoft.AgFoodPlatform/preview/2021-03-31-preview/agfood.json
|
||||
package-version: 1.0.0-beta.2
|
||||
rest-level-client: true
|
||||
security: AADToken
|
||||
security-scopes: https://farmbeats.azure.net/.default
|
||||
use-extension:
|
||||
"@autorest/typescript": "6.0.0-rc.1"
|
||||
emitters:
|
||||
"@azure-tools/cadl-typescript":
|
||||
title: Farmbeats
|
||||
generateMetadata: true
|
||||
generateTest: true
|
||||
packageDetails:
|
||||
name: "@azure-rest/agrifood-farming"
|
||||
description: "Farmbeats Client"
|
||||
version: "1.0.0-beta.1"
|
||||
```
|
||||
~~~
|
||||
|
||||
Here, we need to replace the value in `package-name`, `title`, `description`, `input-file`, `package-version`, `security`,`security-scopes` into **your own service's** `package-name`, `title`, `description` etc. See [security configurations](#how-to-configure-authentication) for more details.
|
||||
|
||||
---
|
||||
**NOTE**
|
||||
|
||||
It's always recommended to replace the version of code generator @autorest/typescript with the latest version you can find in [npmjs.com](https://www.npmjs.com/package/@autorest/typescript) in latest tag.
|
||||
|
||||
If the `input-file` is followed by an `. md` file, you need to replace the `input-file` with `require`. If it is a `JSON` file, do not change it
|
||||
|
||||
**After the first generation, you need to switch `generate-metadata: false` as we have some manual changes in this file and don't want them get overwrite by generated ones.**
|
||||
Here, we need to replace the value in `name`,`description`, `version` in `packageDetails` to **your own service's** package details. Also we have some other options, you could refer to [the link](https://github.com/Azure/autorest.typescript/tree/main/packages/cadl-typescript#emitter-options) for more details.
|
||||
|
||||
---
|
||||
|
||||
1. **edit rush.json**
|
||||
As the libraries in this azure-sdk-for-js repository are managed by rush, you need to add an entry in rush.json under projects section for the first time to make sure it works. For example:
|
||||
**NOTE**
|
||||
|
||||
After the first generation, you need to switch `generateMetadata: false` as we have some manual changes in this file and don't want them get overwrite by generated ones.
|
||||
|
||||
---
|
||||
|
||||
1. **Edit rush.json**
|
||||
As the libraries in azure-sdk-for-js repository are managed by rush, you need to add an entry in rush.json under projects section for the first time to make sure it works. For example:
|
||||
|
||||
```
|
||||
{
|
||||
|
|
@ -79,17 +86,19 @@ We are working on to automatically generate everything right now, but currently
|
|||
|
||||
About the `versionPolicyName`, if the library you are working on is for data-plane, then it should be `client`, if the library you are working on is for control plane, then it should be `mgmt`.
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
1. **run autorest to generate the SDK**
|
||||
1. **Run command to generate the SDK**
|
||||
|
||||
Now you can run this command in swagger folder you just created.
|
||||
We need to configure `--output-dir` to put generated code. The output dir contains two parts: the {SDK_REPO_ROOT} and {PROJECT_ROOT}.
|
||||
|
||||
Assume **{SDK_REPO_ROOT}** is `D:/azure-sdk-for-js` and **{PROJECT_ROOT}** is `sdk/agrifood/agrifood-farming-rest` then we could run this command in **your local Cadl project** to generate the SDK:
|
||||
|
||||
```shell
|
||||
autorest --typescript ./README.md
|
||||
cadl compile . --emit=@azure-tools/cadl-typescript --output-dir=D:/azure-sdk-for-js/sdk/agrifood/agrifood-farming-rest
|
||||
```
|
||||
|
||||
After this finishes, you will see the generated code in `${PROJECT_ROOT}/src` folder.
|
||||
After this finishes, you will see the generated code in `src` folder in your **{PROJECT_ROOT}**.
|
||||
After that, you can get a workable package, and run the following commands to get a artifact if you like.
|
||||
|
||||
```shell
|
||||
|
|
@ -99,19 +108,27 @@ We are working on to automatically generate everything right now, but currently
|
|||
rushx pack
|
||||
```
|
||||
|
||||
But we still need to add some tests for it.
|
||||
The generated code is not good enough to release yet and you need to update it for better usage experience.
|
||||
|
||||
# Improve README.md document
|
||||
|
||||
A minimal README.md is generated by TypeScript emitter and you could improve it with meaningful information to let customers know more about your service.
|
||||
|
||||
# How to write test for RLC
|
||||
|
||||
In order to release it, we need to add some tests for it to make sure we are delivering high quality packages. but before we add the test, we need to add a `generate-test: true` make the code generator generate the necessary change in `package.json` and `tsconfig.json` so that test framework can work. Once the generation finished, you will see a `sampleTest.spec.ts` file in your `{PROJECT_ROOT}/test/public` folder, which only has a empty test and you may change them into test against your own services.
|
||||
In order to release it, we need to add some tests for it to make sure we are delivering high quality packages. But before we add the test, we need to add a `generateTest: true` make the codegen generate the necessary change in `package.json` and `tsconfig.json` so that test framework can work. Once the generation finished, you will see a `sampleTest.spec.ts` file in your `{PROJECT_ROOT}/test/public` folder, which only has an empty test and you may change them into test against your own services.
|
||||
|
||||
See the [Javascript Codegen Quick Start for Test](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/test-quickstart.md) for information on how to write and run tests for the Javascript SDK.
|
||||
See the [Javascript Codegen Quick Start for Test](./Quickstart-on-how-to-write-tests.md) for information on how to write and run tests for the Javascript SDK.
|
||||
|
||||
## Prerequisites
|
||||
1. **Prerequisites**
|
||||
|
||||
- To record and playback the tests, [Docker](https://www.docker.com/) is required when we run the test, as the [test proxy server](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy) is run in a container during testing. When running the tests, ensure the Docker daemon is running and you have permission to use it.
|
||||
To record and playback the tests, [Docker](https://www.docker.com/) is required when we run the test, as the [test proxy server](https://github.com/Azure/azure-sdk-tools/tree/main/tools/test-proxy) is run in a container during testing. When running the tests, ensure the Docker daemon is running and you have permission to use it.
|
||||
|
||||
1. **run the test**
|
||||
1. **Write the test**
|
||||
|
||||
You could follow the [basic RLC test interaction and recording example](./Quickstart-on-how-to-write-tests.md#example-1-basic-rlc-test-interaction-and-recording-for-azure-data-plane-service) to write your test step by step.
|
||||
|
||||
1. **Run the test**
|
||||
Now, you can run the test like this. If you are the first time to run test, you need to set the environment variable `TEST_MODE` to `record`. This will generate recordings for your test they could be used in `playback` mode.
|
||||
On Linux, you could use `export` to set env variable:
|
||||
```shell
|
||||
|
|
@ -137,12 +154,12 @@ See the [Javascript Codegen Quick Start for Test](https://github.com/Azure/azure
|
|||
|
||||
# How to write samples
|
||||
|
||||
We author TypeScript samples under the `samples-dev` folder. You can use sample-dev template for reference [samples-dev folder](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/template/template/samples-dev) folder and update the relevant information for your service such as package-name, sample code, description, etc.
|
||||
We author TypeScript samples under the `samples-dev` folder. You can use sample-dev template for reference [samples-dev folder](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/template/template/samples-dev) folder and update the relevant information for your service such as package-name, sample code, description, etc.
|
||||
After the samples-dev folder change is finished, you will need to change the tsconfig.json to make sure the dev samples can be compiled and build correctly.
|
||||
|
||||
You will need to add this part to the "compilerOptions" of your tsconfig.json file so that the Samples engine could resolve the sample-dev package against the source code of the SDK.
|
||||
``` json
|
||||
"paths": { "@msinternal/sql-resource-manager": ["./src/index"] }
|
||||
"paths": { "@azure-rest/agrifood-farming": ["./src/index"] }
|
||||
```
|
||||
And change the *"include"* part into
|
||||
```json
|
||||
|
|
@ -165,7 +182,7 @@ Now, you can generate both JavaScript and TypeScript workable samples with the f
|
|||
```shell
|
||||
npm install -g common/tools/dev-tool # make sure you are in the azure-sdk-for-js repo root directory
|
||||
cd ${PROJECT_ROOT}
|
||||
dev-tool samples publish -f
|
||||
npx dev-tool samples publish -f
|
||||
```
|
||||
You will see the workable samples in the `${PROJECT_ROOT}/samples` folder.
|
||||
|
||||
|
|
@ -174,10 +191,27 @@ After you have finished the generation and added your own tests or samples, You
|
|||
```shell
|
||||
cd ${PROJECT_ROOT} && rushx format
|
||||
```
|
||||
|
||||
Also we'll recommand you to run `lint` command to analyze your code and quickly find any problems.
|
||||
|
||||
```shell
|
||||
cd ${PROJECT_ROOT} && rushx lint
|
||||
```
|
||||
|
||||
And we could use `lint:fix` if there are any errors.
|
||||
|
||||
```shell
|
||||
cd ${PROJECT_ROOT} && rushx lint:fix
|
||||
```
|
||||
|
||||
# How to do customizations
|
||||
There is many information about the SDK that AutoRest will never know, so you may want to do your customizations based on generated code.
|
||||
|
||||
We collect some common customization cases and you can read [Customization on the RLC rest-level client libraries](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/RLC-customization.md) for more details.
|
||||
|
||||
# How to create package
|
||||
|
||||
Now we can use the exact same steps to build an releasable artifact.
|
||||
Now we can use the exact same steps to build a releasable artifact.
|
||||
|
||||
```shell
|
||||
rush update
|
||||
|
|
@ -229,39 +263,30 @@ Please change the paths.include value as your own project path, and change the A
|
|||
|
||||
If there's already a ci.yml file in your project path. then the only thing you need to do is to add the Artifacts name and safeName of yours into that ci.yml.
|
||||
|
||||
Please notice the Artifacts name should align with your package name. Here the package name is `@azure-rest/agrifood-farming` so the relevant Artifacts name is `azure-rest-agrifood-farming`.
|
||||
|
||||
|
||||
# Prepare PR
|
||||
|
||||
Cadl emitter can only help you generate SDK code, there is something you need to update manually:
|
||||
|
||||
## CHANGELOG.md
|
||||
|
||||
CHANGELOG can help customers know the change of new version quickly, so you need to update the it according to the change of this new version. It is also necessary to update release date like `1.0.0-beta.1 (2022-11-11)`(rough time is fine and no need to be very accurate).
|
||||
|
||||
## Version Number
|
||||
|
||||
You shall update the version number according to [semantic versioning rule](https://semver.org/).
|
||||
|
||||
## Test recordings
|
||||
|
||||
Please ensure that your test recordings are committed together with your code.
|
||||
|
||||
## Fix CI for PR
|
||||
You may meet the CI failures after submitting the PR, so please refer to [Troubleshoot CI Failure](./Troubleshoot-ci-failure.md) to fix it.
|
||||
|
||||
# Create API View
|
||||
You may also want to create API View when submitting a PR. You can do it easily by uploading a json file to [API View Website](https://apiview.dev/). The json file is under `<you-sdk-folder>/temp`, and its name ends with `api.json`. For example: `sdk/compute/arm-compute/temp/arm-compute.api.json`.
|
||||
When submitting a PR our pipeline would automatically prepare the API view in [API View Website](https://apiview.dev/). You could see an [example link](https://github.com/Azure/azure-sdk-for-js/pull/23866#issuecomment-1316259448) here. Then you could click the API view link in that comment to know more details.
|
||||
# Release
|
||||
|
||||
# How to do customizations
|
||||
There is many information about the SDK that AutoRest will never know, so you may want to do your customizations based on generated code.
|
||||
|
||||
We collect some common customization cases and you can read [Customization on the RLC rest-level client libraries](https://github.com/Azure/azure-sdk-for-js/blob/main/documentation/RLC-customization.md) for more details.
|
||||
|
||||
# How to configure authentication
|
||||
Autorest only support two types of authentication: Azure Key Credential(AzureKey) and Token credential(AADToken), any other will need to be handled manually.
|
||||
|
||||
This could be either configured in OpenAPI spec or configuration file e.g `README.md`. You could learn more in [Authentication in AutoRest](https://github.com/Azure/autorest/blob/main/docs/generate/authentication.md).
|
||||
|
||||
Here are the details if we configure in README.md file.
|
||||
- Support AAD token authentication
|
||||
```yaml
|
||||
security: AzureKey
|
||||
security-header-name: Your-Subscription-Key
|
||||
```
|
||||
- Support key authentication
|
||||
```yaml
|
||||
security: AADToken
|
||||
security-scopes: https://yourendpoint.azure.com/.default
|
||||
```
|
||||
- Support both credentials
|
||||
```yaml
|
||||
security:
|
||||
- AADToken
|
||||
- AzureKey
|
||||
security-header-name: Your-Subscription-Key
|
||||
security-scopes: https://yourendpoint.azure.com/.default
|
||||
```
|
||||
- Disable neither authentications
|
||||
```yaml
|
||||
add-credentials: false
|
||||
```
|
||||
After the PR is merged, it is time to release package. Here is the [Release Checklist](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/8/Release-Checklist?anchor=prepare-release-script) you should know before release.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,11 @@
|
|||
# Overview
|
||||
This doc shows some common problems and resolution in CI.
|
||||
|
||||
# Broken links
|
||||
|
||||
|
||||
Add the broken links into [eng/ignore-links.txt](https://github.com/Azure/azure-sdk-for-js/blob/main/eng/ignore-links.txt) file to bypass this verification or you could update the broken links to valid ones, see [example pr here](https://github.com/Azure/azure-sdk-for-js/pull/23429/commits/1a7b74c4bdad27e423a355a4c7f3dde4ac3c83bc).
|
||||
|
||||
|
||||
## Check spelling (cspell)
|
||||
For new service the error usually happens, Fix spelling in code or in markdown at file [.vscode/cspell.json](https://github.com/Azure/azure-sdk-for-js/blob/main/.vscode/cspell.json). See an example in [devcenter pr](https://github.com/chrissmiller/azure-sdk-for-js/commit/ef18dccae59e98185e3854f8b087230b65735744).
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 29 KiB |
Загрузка…
Ссылка в новой задаче