diff --git a/documentation/api-scenario/how-to/generateABasicApiScenario.md b/documentation/api-scenario/how-to/GenerateABasicApiScenario.md similarity index 96% rename from documentation/api-scenario/how-to/generateABasicApiScenario.md rename to documentation/api-scenario/how-to/GenerateABasicApiScenario.md index 3430e518ed23..19d6e75c4093 100644 --- a/documentation/api-scenario/how-to/generateABasicApiScenario.md +++ b/documentation/api-scenario/how-to/GenerateABasicApiScenario.md @@ -16,7 +16,7 @@ npm i -g oav 1. Compile Swagger into dependencies.json with Restler. ```bash -docker run --rm -v $(pwd)/specification:/swagger -w /swagger/.restler_output mcr.microsoft.com/restlerfuzzer/restler:v8.5.0 dotnet /RESTler/restler/Restler.dll compile --api_spec /swagger/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json +docker run --rm -v $(pwd)/specification:/swagger -w /swagger/.restler_output mcr.microsoft.com/restlerfuzzer/restler:v8.6.0 dotnet /RESTler/restler/Restler.dll compile --api_spec /swagger/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json ``` 2. Generate a basic API Scenario file. diff --git a/documentation/api-scenario/how-to/QuickStart.md b/documentation/api-scenario/how-to/QuickStart.md index 9711a3b43936..dd1af850e5b1 100644 --- a/documentation/api-scenario/how-to/QuickStart.md +++ b/documentation/api-scenario/how-to/QuickStart.md @@ -146,7 +146,3 @@ After you import Postman collection, you will get such requests. Now you could d #### 5. Manual update API Scenario or example After debug with Postman, you need to rewrite back all the updated values and run `oav run -e ` again. The result should be successful. - -## Feedback - -If you have any question, feel free to send email to vscswagger@microsoft.com diff --git a/documentation/api-scenario/how-to/integrateWithArmTemplate.md b/documentation/api-scenario/how-to/ResolveDependencies.md similarity index 89% rename from documentation/api-scenario/how-to/integrateWithArmTemplate.md rename to documentation/api-scenario/how-to/ResolveDependencies.md index 53ed14652a78..09cda2df6a03 100644 --- a/documentation/api-scenario/how-to/integrateWithArmTemplate.md +++ b/documentation/api-scenario/how-to/ResolveDependencies.md @@ -1,11 +1,17 @@ -# Integrate with ARM Template +# Resolve external dependencies ## Background -In some cases, we need to do some more complex operations in some scenarios, for example, +In some cases, we need to do more complex operations in some scenarios, like provisioning cross-RP resources as dependencies, calling cross-RP REST API in between the steps of a scenario, or executing some customized PowerShell/Azure CLI scripts. Some concrete examples are: -- Provisioning virtual network with subnet/publicIP/securityGroup and network interface before creating a VM. -- Upload a jar file to some storage blob after creating a Spring Cloud service. +- Provisioning virtual network with subnet/publicIP/securityGroup and network interface with Network RP before creating a VM with Compute RP. +- Creating a private endpoint connection with Network RP between creating AppConfiguration configuration stores and calling its private endpoint related REST APIs. +- Uploading a jar file to some storage blob after creating a Spring Cloud service with AppPlatform RP. + +To support these complex scenarios, we introduce two key features in API Scenario: + +- External operation reference in step definition: We support referencing external operations in step definition, which can be used to call cross-RP REST API before a scenario or in between the steps of a scenario. +- ARM Template integration: We support creating external Azure resources with ARM Template and executing Azure Powershell or Azure CLI scripts with ARM Template deployment script. ## Examples diff --git a/documentation/api-scenario/readme.md b/documentation/api-scenario/readme.md index 52a28200bdf6..5744871ee12a 100644 --- a/documentation/api-scenario/readme.md +++ b/documentation/api-scenario/readme.md @@ -12,11 +12,11 @@ API Scenario is a YAML file defining RESTful API usage scenarios of your service ![demo](./how-to/runApiTest.gif) -## Quick start +## Quick starts - [Example: Write and run your first API scenario file](./how-to/QuickStart.md) -- [Example: Generate a basic API scenario file](./how-to/generateABasicApiScenario.md) -- [Example: Integrate with ARM Template](./how-to/integrateWithArmTemplate.md) +- [Example: Generate a basic API scenario file](./how-to/GenerateABasicApiScenario.md) +- [Example: Resolve external dependencies](./how-to/ResolveDependencies.md) - [API scenario file sample](../samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/quickStart.yaml) ## References @@ -25,3 +25,10 @@ API Scenario is a YAML file defining RESTful API usage scenarios of your service - [API Scenario Variable Definition Reference](./references/Variables.md) - [API Scenario Runner Reference](./references/Runner.md) - [API Scenario JSON Schema](./references/v1.1/schema.json) + +## Feedback + +If you have any question or need support, feel free to contact us via: +- [StackOverflow](https://stackoverflow.microsoft.com/posts/tagged/28051) +- Teams channel: https://aka.ms/SwaggerSupport (for MS FTEs) +- Email: vscswagger@microsoft.com. diff --git a/documentation/api-scenario/references/ApiScenarioDefinition.md b/documentation/api-scenario/references/ApiScenarioDefinition.md index 505ecb0edc3b..66d8fbc073a5 100644 --- a/documentation/api-scenario/references/ApiScenarioDefinition.md +++ b/documentation/api-scenario/references/ApiScenarioDefinition.md @@ -44,15 +44,20 @@ scenarios: - **scope** - **Type:** Required, Enum - - **Enum:** ResourceGroup, Subscription, Tenant - - Now only "ResourceGroup" is supported. - - **ResourceGroup:** All of the following API scenario and steps should be under some resourceGroup. It means: + - **Enum:** ResourceGroup, Subscription, Tenant, None + - **ResourceGroup:** All scenarios and steps should be executed under some resourceGroup. It means: - The consumer (API scenario runner or anything consumes API scenario) SHOULD maintain the resource group itself. Usually it requires user to input the subscriptionId/location, then it creates the resource group before test running, and deletes the resource group after running - The consumer SHOULD set the following variables: - **subscriptionId** - **resourceGroupName** - **location** - For details of how variables work please see [Variables](./Variables.md) + - **Subscription:** All scenarios and steps will be executed under some subscription. It means: + - No resource group need to be created. + - The consumer SHOULD set the following variables: + - **subscriptionId** + - **Tenant:** All scenarios and steps will be executed under tenant scope. + - **None:** None of the assumptions above will be made. Use this if the scenario is for data-plane APIs. - **variables** - **Type:** Optional, Map of Strings or Variables - See [Variables](./Variables.md) diff --git a/documentation/api-scenario/references/v1.2/schema.json b/documentation/api-scenario/references/v1.2/schema.json index feaa7aba5b8c..b16aba41aa15 100644 --- a/documentation/api-scenario/references/v1.2/schema.json +++ b/documentation/api-scenario/references/v1.2/schema.json @@ -6,6 +6,8 @@ "type": "string", "enum": [ "ResourceGroup", + "Subscription", + "Tenant", "None" ], "default": "ResourceGroup" diff --git a/documentation/ci-fix.md b/documentation/ci-fix.md index 7167debe7100..8e020c1d105a 100644 --- a/documentation/ci-fix.md +++ b/documentation/ci-fix.md @@ -127,7 +127,7 @@ This CI check is to test service API readiness, by running API Scenario test to Note: Currently only applicable to management plane APIs, and target ARM region is `US West Central` - the SDP pilot region. -To fix the check, download the artifact `api-test-report` from Azure pipeline where you can find the report.html and auto generated API Scenario file as baseline, then refer to [API Scenario documentation](./api-scenario/readme.md) to run and debug it locally. After local debug, commit the API Scenario file into your working branch and then the CI check will use the committed API Scenario file to re-run the test. +To fix the check, download the artifact `api_scenario_test_output` from Azure pipeline where you can find the report.html and auto generated API Scenario file as baseline, then refer to [API Scenario documentation](./api-scenario/readme.md) to run and debug it locally. After local debug, commit the API Scenario file and `readme.test.md` file into your working branch and then the CI check will use the committed API Scenario file to re-run the test. ## SDK Track2 Validation