{"metadata":{},"top_logprobs":0,"temperature":1,"top_p":1,"service_tier":"default","previous_response_id":"resp_0202bcdfcc870077006994c20600bc8193ac6f6fbd966b8a93","model":"gpt-4.1","reasoning":{},"background":false,"text":{"format":{"type":"text"},"verbosity":"medium"},"tools":[{"type":"mcp","server_label":"api-specs","server_url":"https://gitmcp.io/Azure/azure-rest-api-specs","require_approval":"always"}],"tool_choice":"auto","truncation":"disabled","id":"resp_0202bcdfcc870077006994c20daed081939c9d8d617a1b2b86","object":"response","status":"completed","created_at":1771356686,"completed_at":1771356695,"error":null,"incomplete_details":null,"output":[{"type":"mcp_call","id":"mcp_0202bcdfcc870077006994c20f70288193be89504d3c043643","agent_reference":{"type":"agent_reference","name":"cs-e2e-tests-client","version":"1"},"response_id":"resp_0202bcdfcc870077006994c20daed081939c9d8d617a1b2b86","server_label":"api-specs","name":"fetch_azure_rest_api_docs","arguments":"{}","output":"# Azure/azure-rest-api-specs/documentation Documentation\nBelow is a structured llms.txt index of Markdown files extracted from the /documentation folder. Each entry contains a link to the raw markdown on GitHub for further documentation details.\n\n\n## Root Files\n\n\n\n- [Breaking changes guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Breaking%20changes%20guidelines.md): Azure REST API Version Change Guide\nThis document provides guidance to Azure Service teams on making changes to REST APIs, focusing on updating API versions to maintain backwards compatibility. It supplements the official Microsoft REST API guidelines and outlines scenarios that require a new API version, including removing or renaming properties, changing property types, and adding new required properties. The guide also covers non-breaking changes, such as adding new APIs, read-only fields, and bug fixes. Understanding these guidelines is crucial for ensuring smooth API evolution.\n\nFor example, if a property \"foo\" was a boolean in v1 but is changed to a string, the API version must be updated:\n```json\n// v1\n{\n  \"foo\": true\n}\n// v2\n{\n  \"foo\": \"string\"\n}\n```\nSimilarly, adding a new required property to the request body is a breaking change:\n```json\n// v1\n{\n  \"name\": \"resource\"\n}\n// v2\n{\n  \"name\": \"resource\",\n  \"newProperty\": \"requiredValue\"\n}\n```\nAdditional examples include changes to property names, enum values, and API behavior.\n\nKEY TECHNICAL TERMS:\n\n1. Backwards compatibility\n2. Breaking changes\n3. API versioning\n4. REST API guidelines\n5. Property type changes\n6. Enum changes\n7. API deprecation policy\n8. Resource naming rules\n9. Non-breaking changes\n10. API evolution\n\n\n- [BreakingChange-Oad-Rules-Mapping.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/BreakingChange-Oad-Rules-Mapping.md): Azure REST API Breaking Change and OAD Rules Mapping\nThis document outlines the relationship between OpenAPI Diff (OAD) rules and Azure's breaking change policy for REST APIs. It provides a table mapping OAD rules to breaking change categories, detailing changes such as removed or added parameters, changed response codes, and modified operation IDs. The rules are identified by IDs (e.g., 1002-1046) and describe specific changes like protocol support, request/response body formats, and property additions/removals. Understanding these rules helps in assessing the impact of API changes on existing clients and ensuring backward compatibility. For instance, rules like [1002 - ProtocolNoLongerSupported](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1002.md) and [1038 - AddedPath](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1038.md) illustrate how changes are categorized.\n\nExample of OAD rule: \n- [1002 - ProtocolNoLongerSupported](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1002.md): Describes a breaking change when a protocol is no longer supported.\n\nAdditional code examples are available throughout the document, detailing various rules such as [AddedEnumValue](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1020.md) and [TypeFormatChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1023.md).\n\nKEY TECHNICAL TERMS:\n1. OAD Rules\n2. Breaking Change Policy\n3. Azure REST API\n4. OpenAPI Diff\n5. API Versioning\n6. Backward Compatibility\n7. REST API Changes\n8. API Breaking Changes\n9. OpenAPI Specifications\n10. Azure API Guidelines\n\n\n- [FAQ.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/FAQ.md): Azure API Spec PR Review FAQ\nThis document provides answers to frequently asked questions during Azure API spec PR review. It covers topics such as onboarding to API spec PR review process, fixing validation failures, generating SDKs, documents, and examples from API specs. The document is divided into sections, each addressing a specific question. For instance, new users can start by referring to the [API specs document](https://eng.ms/docs/products/azure-developer-experience/design/api-specs/api-specs#create-your-rest-api-definition) for an introduction. To fix validation failures, refer to the [validation table](#validation) which lists common issues and their fixes.\n\n```markdown\n// Example of fixing validation failure\n| Validation | Description | How to fix |\n| --- | --- | --- |\n| Model Validation | Model validation enforces correctness between example and swagger.  | [Fix Model Validation](https://aka.ms/ci-fix#model-validation) |\n```\n\nThe document also provides resources for [generating SDKs from API specs](https://eng.ms/docs/products/azure-developer-experience/develop/sdk-generate) and [creating documentation](https://eng.ms/docs/products/azure-developer-experience/design/api-docs).\n\nAdditional code examples are available in the document, including [Swagger Example Generation](https://github.com/Azure/oav/blob/develop/documentation/example-generation.md).\n\n## Key Technical Terms and Topics:\n\n1. API Specs\n2. Swagger\n3. Validation Failure\n4. SDK Generation\n5. Documentation Generation\n6. Example Generation\n7. Model Validation\n8. Lint Diff\n9. Breaking Change\n10. Avocado\n\nNote that I have only extracted key terms and concepts directly mentioned in the document and provided a concise summary of the content.\n\n\n- [Getting started with OpenAPI specifications.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Getting%20started%20with%20OpenAPI%20specifications.md): OpenAPI Specification for Azure REST API\nThe OpenAPI Specification, formerly known as Swagger Specification, is a format for describing REST APIs. It allows you to describe your entire API, including available endpoints, operations, parameters, authentication methods, and more. Currently, Azure supports OpenAPI Specification 2.0 or Swagger V2.0. To get started, you can refer to helpful resources such as the GitHub flow, contributing guidelines, Azure REST API guidelines, and OpenAPI Style Guide. The specification includes essential information like endpoints, operations, parameters, and authentication methods. For example, you can describe available endpoints like `/users` and operations on each endpoint like `GET /users` and `POST /users`. \n\nThe structure of a Swagger specification and sample files are provided for reference. Additionally, there are guidelines for authoring good Swagger descriptions, validation tools, and breaking changes.\n\nExample:\n```json\n// Sample Swagger specification\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Your Service Name\",\n    \"description\": \"Your service description\",\n    \"version\": \"1.0.0\"\n  },\n  \"paths\": {\n    \"/users\": {\n      \"get\": {\n        \"summary\": \"Get users\",\n        \"responses\": {\n          \"200\": {\n            \"description\": \"OK\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nThere are also additional examples in the `samplefiles` directory.\n\nKEY TECHNICAL TERMS:\n1. OpenAPI Specification\n2. Swagger Specification\n3. REST APIs\n4. Azure REST API guidelines\n5. OpenAPI Style Guide\n6. Swagger V2.0\n7. API description format\n8. Endpoints\n9. Operations\n10. Validation tools\n\n\n- [Getting-started-with-TypeSpec-specifications.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Getting-started-with-TypeSpec-specifications.md): What is a TypeSpec Specification in Azure REST API\nTypeSpec is a versatile language for describing cloud service APIs and generating API description languages, client and service code, documentation, and other related assets. It provides highly extensible core language primitives that can describe API structures common among REST, GraphQL, gRPC, and other protocols. Within the azure-rest-api-specs repository, TypeSpec serves as the source to generate corresponding OpenAPI 2.0 (swagger) API documentation. To get started with TypeSpec, one should include a `tspconfig.yaml` file, an examples folder, and follow specific folder structure guidelines. For instance, the TypeSpec folder name for ARM services should end with `.Management`. A `tspconfig.yaml` file for ARM template may look like the following:\n\n```yml\n# tspconfig.yaml example\n```\nFor Data-Plane, a `tspconfig.yaml` starting template is provided. \n```yml\n# tspconfig.yaml example for Data-Plane\n```\nThe document also provides detailed information on setting up a local environment, folder structure, and regenerating SDK projects.\n\nAdditional code examples include setting up a new TypeSpec project and regenerating SDK projects.\n\nKEY TECHNICAL TERMS:\n- TypeSpec\n- Azure REST API guidelines\n- OpenAPI 2.0 (swagger)\n- tspconfig.yaml\n- typespec-autorest\n- ARM template\n- Data-Plane\n- typespec-core\n- typespec-resource-manager\n- API description languages\n\n\n- [Semantic-and-Model-Violations-Reference.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Semantic-and-Model-Violations-Reference.md): Semantic and Model Violations Reference for Azure REST API\nThis document lists automated rules validated against Swagger specs using the OAV tool, providing error information, descriptions, and tips for fixing violations. It covers various aspects, including validation errors, warnings, and rule descriptions.\n\nThe document provides a comprehensive list of potential issues that can arise when creating or updating Swagger specifications for Azure REST APIs. These issues range from simple errors like invalid content types or missing required properties to more complex problems like circular inheritance or semantic validation errors.\n\nTo effectively use this document, one should first understand the nature of the error or warning they are encountering. For instance, if there's an \"INVALID_CONTENT_TYPE\" error, the document advises fixing the content-type to one of the supported values. Similarly, for a \"MISSING_PATH_PARAMETER_DECLARATION\" error, one should add the declaration or remove the definition of the parameter.\n\nHere is an example of how to address a common issue:\n\n```json\n// Example of fixing INVALID_TYPE error\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\"\n    }\n  },\n  \"required\": [\"name\"]\n}\n```\n\nSome key topics and terms extracted from the document include:\n\n1. **Validation Errors**: These are errors that occur when the Swagger specification fails validation, such as missing required properties, invalid types, or semantic validation errors.\n2. **INVALID_REFERENCE**: This error occurs when a reference in the Swagger spec is invalid.\n3. **CIRCULAR_INHERITANCE**: This happens when a schema inherits from itself.\n4. **MISSING_PATH_PARAMETER_DECLARATION**: A path parameter is declared but not defined.\n5. **INVALID_PARAMETER_COMBINATION**: Body and formData parameters are mutually exclusive.\n6. **DUPLICATE_OPERATIONID**: Multiple operations with the same operationId are not allowed.\n7. **SEMANTIC_VALIDATION_ERROR**: Errors occur during semantic validation of the Swagger spec.\n\nBy understanding and addressing these issues, developers can ensure their Swagger specifications are accurate, complete, and follow best practices for Azure REST APIs. \n\nExamples of errors and fixes:\n\n- **INVALID_TYPE**: Expected type 'int' but found type 'string'.\n- **MISSING_REQUIRED_PROPERTY**: Missing required property 'name'.\n\nThe document serves as a critical resource for developers to identify, resolve, and prevent common errors in Swagger specifications for Azure REST APIs.\n\n\n- [SwaggerValidationTools.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/SwaggerValidationTools.md): Validation Tools for Azure REST API Specifications\nThis document provides information on tools available for validating Azure REST API specifications against accepted guidelines. It lists various tools that can be used locally to ensure specifications conform to guidelines before sending a pull request. The tools include Linter Validator, Static Validator (Semantic), Static Validator (Model), and Swagger diff tool. To use these tools, one needs to install Node.js (7.10.0 or greater) and then install the required tools using npm. The document provides commands for installing and using each tool, such as `autoRest`, `oav validate-spec`, `oav validate-example`, and `oad compare`. Additionally, it mentions a suppression process for Microsoft FTEs to request suppression of false positive errors.\n\nExample usage:\n- `npm install -g autorest`\n- `autoRest <path to readme.md> --azure-validator=true`\n\nThe document also mentions other code examples for `oav validate-spec` and `oad compare`.\n\nEXTRA EXAMPLES AVAILABLE: Swagger validation, suppression process.\n\nKEY TERMS:\n- Azure REST API\n- Validation tools\n- Linter Validator\n- Static Validator (Semantic)\n- Static Validator (Model)\n- Swagger diff tool\n- Node.js\n- npm\n- autorest\n- oav\n- oad\n- suppression process\n\n\n- [ci-fix.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/ci-fix.md): CI Fix Guide for Azure REST API Specs\nThis guide provides detailed troubleshooting instructions for automated validation tooling checks running on Azure REST API specs PRs. It covers various checks, including CredScan, PoliCheck, SDK Validation, Swagger APIView, Swagger ApiDocPreview, Swagger Avocado, Swagger BreakingChange, Swagger LintDiff, Swagger Lint(RPaaS), Swagger ModelValidation, Swagger PrettierCheck, Swagger SemanticValidation, Spell Check, and TypeSpec Validation. The guide also explains the suppression process and lists obsolete checks.\n\nTo troubleshoot issues with these checks, follow the steps outlined in the guide. For example, to run `oad` locally for Swagger BreakingChange checks, use the following command:\n\n```powershell\nnpm install -g @azure/oad\noad compare <old-spec-path> <new-spec-path>\n```\n\nSimilarly, to validate examples with Swagger ModelValidation, use:\n\n```powershell\nnpm install -g oav\noav validate-example <openapi-spec-path>\n```\n\nThe guide also provides information on how to update spec files using Prettier and how to add words to the override list for spell checking.\n\nKEY TECHNICAL TERMS:\n\n1. Azure REST API specs\n2. Automated validation tooling\n3. Swagger APIView\n4. Swagger BreakingChange\n5. Swagger LintDiff\n6. TypeSpec Validation\n7. PrettierCheck\n8. SemanticValidation\n9. ModelValidation\n10. Spell Check\n\nThese terms are crucial for understanding and troubleshooting the various checks and validations involved in the Azure REST API specs PR build process.\n\n\n- [creating-swagger.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/creating-swagger.md): AutoRest Swagger Conventions and Extensions\nThis document explains the conventions and extensions used by AutoRest in processing Swagger to produce client libraries. It covers various aspects of Swagger, including Info Object, Host, Schemes, Consumes/Produces, Paths, Path Item, Operation and OperationId, Parameters, Responses, Model Types, Model Inheritance, Polymorphic Response Models, Resource Flattening, Enums, Paging, URL Encoding, Long Running Operations, and Global Parameters. The document provides a comprehensive guide on how to use Swagger with AutoRest to generate client libraries.\n\nFor example, consider the following Swagger definition:\n```json5\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"MyClientName\",\n  }\n}\n```\nThis will generate a client library with a class named `MyClientName`.\n\nAnother example is the use of `x-ms-enum` extension:\n```json5\n\"accountType\": {\n  \"type\": \"string\",\n  \"enum\": [\n    \"Standard_LRS\",\n    \"Standard_ZRS\",\n    \"Standard_GRS\",\n    \"Standard_RAGRS\",\n    \"Premium_LRS\"\n  ],\n  \"x-ms-enum\": {\n    \"name\": \"AccountType\",\n    \"modelAsString\": false\n  }\n}\n```\nThis will generate an enum type in C#.\n\nKEY TECHNICAL TERMS:\n\n1. AutoRest\n2. Swagger\n3. OpenAPI Specification\n4. x-ms-enum\n5. x-ms-pageable\n6. x-ms-long-running-operation\n7. Resource Flattening\n8. Model Inheritance\n9. Polymorphic Response Models\n10. URL Encoding\n\nSome other code examples available in document:\n- Model Inheritance \n- Paging with x-ms-pageable \n- Long Running operation \n- Enums with x-ms-enum\n\n\n- [directory-structure.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/directory-structure.md): Azure REST API Specifications Directory Structure\nThe `specification` directory in the Azure REST API specifications repository contains the directory structure and guidelines for organizing service specifications. It is divided into team folders, each containing TypeSpec specifications, resource manager, and data-plane services. The structure reflects key concepts such as services, service groups, and uniform versioning. Teams can organize their services under `resource-manager` or `data-plane` folders, following specific naming conventions and folder layouts. For example, a service folder might be located at `specification/<azureTeam>/resource-manager/<RPNS>/<service>`, where `<azureTeam>` is the team name, `<RPNS>` is the Resource Provider namespace, and `<service>` is the service name.\n\n```markdown\nExample of service folder structure:\n- specification\n  - <azureTeam>\n    - resource-manager\n      - <RPNS>\n        - <service>\n          - stable\n            - <apiVersion>\n          - preview\n            - <apiVersion-preview>\n```\n\nThe document also provides guidelines for naming conventions, migrating from legacy directory structures, and deprecated directory structures.\n\nAdditional code examples and information can be found in the [TypeSpec directory structure](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md) and [API versioning guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning).\n\nKEY TERMS:\n1. TypeSpec\n2. Resource Provider Namespace (RPNS)\n3. Service group\n4. Grouping directory\n5. Uniform versioning\n6. AutoRest config\n7. OpenAPI specifications\n8. Azure Team\n9. Data-plane services\n10. Resource Manager services\n\n\n- [glossary.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/glossary.md): Glossary of Terms for Azure REST API Specifications\nThis document defines key terms used in the Azure REST API specifications, including grouping directory, resource type, service, service group, and uniform versioning. A grouping directory is a root folder for data-plane service folders, where each service versions uniformly but independently of others. A service is a set of operation endpoints with a cohesive, uniformly versioned experience for customers. A service group is a set of services sharing a common ARM Resource Provider namespace. The document explains how services and service groups are structured and related to ARM Resource Provider namespaces.\n\nFor example, a service can be found in a path like `specification/containerservice/resource-manager/Microsoft.ContainerService/aks`, and a service group can be seen in `specification/containerservice/resource-manager/Microsoft.ContainerService`. \n\nAdditional code examples illustrate service and service group structures, such as [`specification/containerservice/resource-manager/Microsoft.ContainerService/aks`] and [`specification/containerservice/resource-manager/Microsoft.ContainerService`].\n\nCODE EXAMPLES:\n- Service path: `specification/<azureTeamName>/resource-manager/<RPNS>/<service>`\n- Service group path: `specification/<azureTeamName>/resource-manager/<RPNS>`\n\nEXTRA EXAMPLES: Directory structure and versioning examples are also provided.\n\nKEY TERMS:\n1. Grouping directory\n2. Resource type\n3. Service\n4. Service group\n5. Uniform versioning\n6. ARM Resource Provider namespace\n7. Resource Provider (RP) namespace\n8. Data-plane service\n9. Directory structure\n10. Uniform versioning article\n\n\n- [openapi-authoring-automated-guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/openapi-authoring-automated-guidelines.md): Azure/azure-rest-api-specs Documentation\nNo summary available\n\n\n- [openapi-authoring-manual-guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/openapi-authoring-manual-guidelines.md): ** OpenAPI Specifications Authoring Manual Guidelines\n** \nThis document outlines the manual guidelines for authoring OpenAPI (Swagger) specifications. It provides a set of rules to ensure that the specifications are accurate, consistent, and follow best practices. The guidelines are categorized into errors and warnings, with errors requiring immediate attention before sending a pull request for review. The rules cover aspects such as resource model naming, required parameters, read-only properties, and documentation quality. Authors are expected to conform to these guidelines to ensure that the OpenAPI specifications correctly represent the underlying REST API. For example, a resource model name MUST be the same as the singular form of the resource type, and required parameters MUST be accurately labeled as \"required\": true in the OpenAPI specification. Additionally, descriptions MUST NOT contain spelling errors, grammatical errors, or dummy texts.\n\n**CODE EXAMPLES:** \n- Resource Model name: `VirtualMachine` (singular form) instead of `virtualMachines`.\n- Required parameters: `parameters: [ { \"name\": \"resourceGroupName\", \"required\": true } ]`.\n\nThere are more code examples available in the document that demonstrate how to apply these guidelines.\n\n**KEY TECHNICAL TERMS AND TOPICS:**\n\n1. OpenAPI Specifications\n2. Swagger\n3. Resource Model\n4. x-ms-parameter-location\n5. x-ms-mutability\n6. x-ms-enum\n7. External Documentation\n8. OData parameters\n9. API Documentation\n10. REST API Specs\n\n\n- [swagger-accuracy-report.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-accuracy-report.md): Service Contract Accuracy Report for Azure REST API\nThe Service Contract Accuracy Report ensures that service contracts accurately reflect true service behavior. This report is generated using RESTler and OAV tools, which test all service operations and compare actual requests and responses against the contract. To improve API coverage, users can download RESTler configuration files, modify them, and run RESTler locally. The process involves creating an authentication script, modifying configuration files (dictionary, annotation, and engine settings), and testing changes locally. After making improvements, the modified configuration files can be uploaded to the azure-rest-api-specs repository to re-run the Service Contract Accuracy report. \n\nExample authentication script for obtaining AAD tokens:\n```sh\n#!/bin/bash\n\nfind . -name 'token.json' -depth 1 -mtime -1h | grep . &> /dev/null || az account get-access-token --scope <AAD Scope for the service>> token.json\n\ntoken=Sanitized -r '.accessToken' token.json)\n\necho \"{'user1':{}, 'user2':{}}\"\necho \"Authorization: bearer ${token}\"\necho \"Authorization: shadow_unit_test_token\"\n```\n\nExample command for running RESTler locally:\n>Restler.exe test --dictionary_file dict.json --grammar_file grammar.py --settings engine_settings.json --token_refresh_command \"/local-scripts/get-token.sh\" --token_refresh_interval 60\n\nThere are additional code examples for dictionary, annotation, and engine settings configuration.\n\nKEY TECHNICAL TERMS:\n1. RESTler\n2. OAV\n3. Service Contract Accuracy Report\n4. Swagger specification\n5. Azure CLI\n6. AAD authentication\n7. RESTler configuration files\n8. Traffic validation pipeline\n9. Engine settings\n10. API coverage\n\n\n- [swagger-authoring-descriptions.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-authoring-descriptions.md): ** Writing Effective Descriptions in Swagger 2.0\n** \nThis document provides guidelines for authoring high-quality descriptions in Swagger 2.0, which become the baseline public Azure REST API documentation. It emphasizes the importance of well-crafted descriptions, offering tips and tools to ensure consistency and professionalism. The guide covers basic rules, such as starting with a capital letter, using correct grammar and spelling, and documenting HTTP status codes. It also suggests good practices, including previewing content, reviewing style guides, and using tools like Grammarly. The descriptions are used not only on learn.microsoft.com but also in client SDKs, Swagger UI, and other REST documentation tools.\n\n**CODE EXAMPLES:** \nNo specific code examples are provided in the document, but it mentions that descriptions can be written in a style similar to this: \"Gets a GitHub-Flavored Markdown (GFM) formatted document that contains the current release notes.\" \n\nAdditional examples of well-written descriptions can be found throughout the document.\n\n**KEY TECHNICAL TERMS AND TOPICS:** \n1. Swagger 2.0\n2. Azure REST API\n3. AutoRest\n4. OpenAPI\n5. Grammarly\n6. Swagger UI\n7. IntelliSense\n8. Microsoft Writing Style Guide\n9. Azure-specific Microsoft Cloud Style Guide\n10. Open Publishing (OP) DocFX tool\n\n\n- [swagger-checklist.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-checklist.md): Swagger Checklist for Microsoft Azure\nThis document provides a checklist for developing Swagger specifications for Microsoft Azure. It outlines requirements and guidelines for creating and validating Swagger documents, including automated and manual rules. The Azure developer experience team has created tools to validate Swagger specifications, such as the AutoRest OpenAPI Validator and Swagger Model Validator. These tools help ensure that Swagger documents meet the necessary requirements and are free of errors. The checklist is continuously updated to reflect issues uncovered during Swagger specification reviews. To get started, developers can install the validation tools on their development machines and use them to validate their Swagger documents as they build them. The [\"x-ms-examples\"](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) extension is used to integrate test examples into Swagger documents.\n\nExample of using AutoRest OpenAPI Validator:\n```bash\n# Activate the OpenAPI validator with --azure-validator\n```\nExample of using Swagger Model Validator with [\"x-ms-examples\"](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) extension:\n```json\n// Sample test examples for this extension can be found in the Redis Cache Swagger\n// https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json\n```\n\nAdditional code examples are available in the [Redis Cache Swagger](https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json).\n\nKEY TECHNICAL TERMS:\n\n* Swagger\n* OpenAPI\n* AutoRest OpenAPI Validator\n* Swagger Model Validator\n* x-ms-examples extension\n* Azure REST API\n* API validation\n* Swagger specification\n* Azure developer experience team \n* Validation tools\n\n\n- [swagger-extensions.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-extensions.md): AutoRest Extensions for OpenAPI 2.0 Documentation\nThis document provides information on AutoRest extensions for OpenAPI 2.0, a specification used for generating client libraries for Azure REST APIs. The document references an external link for detailed information on AutoRest extensions, which enable features such as adding custom headers, supporting polymorphism, and more. It appears to be a brief introduction to the concept, pointing to the main documentation source at https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md. To learn more about using AutoRest extensions, one should visit the provided GitHub link for comprehensive details and usage guidelines.\n\nCODE EXAMPLES:\nNo code examples are directly provided in the given document content.\n\nADDITIONAL EXAMPLES NOTE: The document does not provide additional code examples beyond the reference link.\n\nKEY TECHNICAL TERMS:\n- AutoRest\n- OpenAPI 2.0\n- Azure REST APIs\n- AutoRest extensions\n\n\n- [typespec-end-to-end-scenarios.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/typespec-end-to-end-scenarios.md): TypeSpec End-to-End Scenarios\nThis document outlines the end-to-end scenarios for TypeSpec, a tool for generating SDKs from API specifications. It covers four main user scenarios: TypeSpec project scaffolding, SDK code generation, inner dev loop SDK generation, and outer dev loop. The document provides flowcharts and details for each scenario, including the steps involved, scripts used, and remaining tasks. It aims to provide a smooth process for developers to work with TypeSpec and generate SDKs.\n\nThe document describes the following key scenarios:\n\n*   TypeSpec project scaffolding: creating a new TypeSpec project using `tsp init` and generating swagger examples.\n*   SDK code generation: generating SDK code using TypeSpec.\n*   Inner dev loop SDK generation: generating SDKs locally on a developer's machine.\n*   Outer dev loop: shepherding TypeSpec documents through the Azure/azure-rest-api-specs repository and its dependency repos/branches to different language SDK repos.\n\nExample code:\n```mermaid\nflowchart TD\nclassDef highlight fill:#ffd700\nclassDef grey fill:#CCCCCC,color:#555555;\nUser((::)) --> |Develop in rest-api repo|A[Clone rest-api repo]\nUser((::)) --> |Develop in custom service repo|B1[1.2 `tsp init https://aka.ms/azure-init`]\nB1-->D\nA --> B[1.1 Create folder structure per spec ]\nB --> C[\"1.2 `tsp init https://aka.ms/azure-init`<br>delete package.json in project folder\"]\nC --> D[...iterate on *.tsp specs]\nD ---> |Loop|F\nD --> E[\"1.3 generate swagger examples\n(need a new script)\"]\nE --> F[\"tsp compile . (generate swaggers)\"]\nF --> G1[Copy specs files into rest-api repo]\nG1 --> G2[Optionally: Adopt shift-left pipeline]\nG2--> G\nF --> G[create a spec PR]\n```\nAdditional code examples include PowerShell scripts for TypeSpec project processing, such as `TypeSpec-Project-Process.ps1`, `TypeSpec-Project-Sync.ps1`, and `TypeSpec-Project-Generate.ps1`.\n\nKey technical terms and topics:\n\n1.  TypeSpec\n2.  Azure REST API specs\n3.  SDK generation\n4.  Inner dev loop\n5.  Outer dev loop\n6.  TypeSpec project scaffolding\n7.  TypeSpec project processing scripts (`TypeSpec-Project-Process.ps1`, `TypeSpec-Project-Sync.ps1`, `TypeSpec-Project-Generate.ps1`)\n8.  SDK code generation\n9.  API view generation\n10. CI/CD pipeline\n\n\n- [typespec-rest-api-dev-process.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/typespec-rest-api-dev-process.md): Azure Rest API and SDK Development with TypeSpec\nThis document outlines the process for developing Azure Rest APIs and SDKs using the TypeSpec language. It covers setting up the repository, creating a new TypeSpec project, preparing and submitting a Pull Request, and generating or refreshing SDK code. The guide assumes development in the `azure-rest-api-specs` and `azure-rest-api-specs-pr` repositories. Prerequisites include Node.js LTS version 18 or above and installing required packages with `npm ci`. TypeSpec projects are initialized with `npx tsp init` and compiled with `npx tsp compile`. The document also details generating Swagger examples, creating a Pull Request, and fixing CI check errors.\n\nExample usage of TypeSpec commands:\n```cli\nnpx tsp init https://aka.ms/typespec/azure-init\nnpx tsp compile .\n```\n\nAdditional code examples are available in the document, including generating Swagger examples with `oav generate-examples` and `oav run` commands.\n\nKEY TECHNICAL TERMS:\n\n1. TypeSpec\n2. Azure Rest API\n3. SDK development\n4. Node.js LTS\n5. npm ci\n6. TypeSpec VisualStudio extensions\n7. Dev Containers\n8. Github Codespaces\n9. OpenAPI\n10. Autorest \n\nLet me know if I can help with anything else.\n\n\n- [typespec-structure-guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/typespec-structure-guidelines.md): Guidelines for TypeSpec Project Repositories\nThis document provides guidelines for managing TypeSpec projects for Azure, including the structure of TypeSpec project repositories, service folder structure, libraries for service groups, specification versioning, and utilizing feature branches. The TypeSpec project repositories are organized under the `specification` folder, with each child folder corresponding to a service specification for a specific Azure team. The service folder contains the complete TypeSpec library specification for a service, which may include custom linter rules, methods, etc. \n\nFor example, a service folder for a compute service might include multiple TypeSpec files, such as `Compute.Management`, `Compute.CloudService.Management`, and `Compute.Disk.Management`. \n\n```\n-> specification\n   -> compute\n      -> Compute.Management               (management SDK + service)\n      -> Compute.CloudService.Management  (service)\n      -> Compute.Disk.Management          (service)\n```\n\nThe document also explains how to utilize feature branches for comparing proposed changes directly against the main branch and how to publish specifications by merging Pull Requests.\n\nAdditional code examples include how to reference shared libraries and how to structure service group libraries.\n\nSome key concepts include:\n- TypeSpec project repositories\n- Service folder structure\n- Specification versioning\n- Feature branches\n- Publishing specifications\n\nThe document also provides information on organizing services in folders, utilizing feature branches, and publishing specifications.\n\nKEY TERMS:\n- TypeSpec\n- Azure\n- Service folder structure\n- Specification versioning\n- Feature branches\n- Service group libraries\n- tspconfig.yaml\n- TypeSpec packages\n- Versioning decorators\n- Service specifications\n- Shared libraries\n\n\n- [uniform-versioning.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/uniform-versioning.md): Uniform Versioning in Azure REST API Specifications\nUniform versioning in Azure REST API specifications ensures that a service, its operation endpoints, documentation, and SDKs version in lockstep. This means that when a new service API version is released, a new documentation reference and SDK package must also be released. The service version is represented by a pair of folders, including its lifecycle stage and date, such as `stable/2024-03-05`. Each service within a service group can version independently, but must follow uniform versioning rules. The API version date must be later than the previous date, and `stable` and `preview` API versions cannot have the same date.\n\nFor example, consider a service with the following directory structure:\n```markdown\nservice/\nstable/\n2024-03-05/\nservice.json\noperation1.json\noperation2.json\npreview/\n2024-05-15-preview/\nservice.json\noperation1.json\noperation3.json\n```\nIn this example, the service has two API versions: `2024-03-05` (stable) and `2024-05-15-preview` (preview).\n\nAdditional code examples can be found in the [directory structure article] and [AutoRest config `README.md` file].\n\nCODE EXAMPLES:\n```markdown\n// Example of a service with multiple API versions\nservice/\nstable/\n2024-03-05/\nservice.json\noperation1.json\noperation2.json\npreview/\n2024-05-15-preview/\nservice.json\noperation1.json\noperation3.json\n```\n\nKEY TECHNICAL TERMS:\n\n1. Uniform versioning\n2. Service group\n3. API version\n4. Lifecycle stage\n5. Common-types\n6. AutoRest configuration\n7. Directory structure\n8. API version lifecycle stage\n9. Service version\n10. OpenAPI specification\n\n\n- [x-ms-examples.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/x-ms-examples.md): x-ms-examples Extension for Swagger Specifications\nThe `x-ms-examples` extension is used in Swagger specifications to provide multiple examples of requests and responses for an operation. This extension is a dictionary of different variations of examples for a given operation, allowing service teams to showcase various scenarios, such as different parameters or responses. The examples are stored in separate JSON files, located in an adjacent folder called `examples`, to keep the Swagger specification clean and easy to manage. The extension is applied at the operation level and provides a holistic picture of the entire request/response. For instance, an example file might contain parameters and responses for a specific operation, such as creating a storage account.\n\nExample of `x-ms-examples` extension in Swagger spec:\n```json5\n\"x-ms-examples\": {\n  \"Create a storage account\": { \"$ref\": \"./examples/createStorageAccount.json\" },\n  \"Update a storage account\": { \"$ref\": \"./examples/updateStorageAccount.json\" }\n}\n```\nExample of an individual example file (`createStorageAccount.json`):\n```json5\n{\n  \"parameters\": {\n    \"subscriptionId\": \"34adfa4f-cedf-4dc0-ba29-b6d1a69ab345\",\n    \"resourceGroupName\": \"testrg123\",\n    \"storageAccountName\": \"testacc6141\",\n    ...\n  },\n  \"responses\": {\n    \"200\": {\n      \"headers\": { ... },\n      \"body\": { ... }\n    }\n  }\n}\n```\nAdditional examples include various request/response scenarios, such as GET requests with or without `$expand`.\n\nKEY TECHNICAL TERMS:\n\n1. Swagger specification\n2. x-ms-examples extension\n3. Operation Object\n4. JSON schema\n5. API endpoint\n6. Request/response examples\n7. Swagger spec\n8. Example files\n9. API documentation\n10. REST API documentation\n\n\n\n## api-scenario\n\n\n### how-to\n\n\n\n- [GenerateABasicApiScenario.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/GenerateABasicApiScenario.md): Generate a Basic API Scenario File from Swagger\nThis document provides a step-by-step guide on generating a basic API scenario file from Swagger. It requires the installation of `oav` and `docker` as prerequisites. The process involves compiling Swagger into `dependencies.json` with Restler and then using `oav` to generate the API scenario file. The generated file contains all operations in the Swagger file, ordered by dependencies, with minimum required parameters filled in. The document also offers an alternative approach using Swagger examples to generate the API scenario file. Additionally, it mentions running the API scenario file with `oav run`. \n\nExample commands:\n```bash\ndocker run --rm -v $(pwd)/specification:/swagger -w /swagger/.restler_output mcr.microsoft.com/restlerfuzzer/restler dotnet /RESTler/restler/Restler.dll compile --api_spec /swagger/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json\n```\n```bash\noav generate-api-scenario static --specs specification/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json --dependency specification/.restler_output/Compile/dependencies.json -o specification/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/scenarios\n```\n\nNote that there are additional code examples in the document, including an alternative command that uses Swagger examples.\n\nKEY TECHNICAL TERMS:\n- oav\n- Restler\n- Swagger\n- API scenario file\n- dependencies.json\n- docker\n- Restlerfuzzer\n- API specification\n- Swagger examples\n\n\n- [MakeTestProxyRecording.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/MakeTestProxyRecording.md): Using API Scenario Test and Test-Proxy for Traffic Recording\nThis document explains how to use API Scenario Test and test-proxy to make traffic recording. It assumes familiarity with API Scenario test and focuses on utilizing test-proxy for recording and playback capabilities. The process involves preparing an assets.json file, making recordings, pushing them to an external Git repository, and restoring or resetting recordings as needed. Key steps include starting test-proxy, running API Scenario tests, checking recordings, and pushing or restoring recordings using specific commands.\n\nTo make traffic recording, start by preparing an `assets.json` file under the `scenarios/` folder with content specifying the assets repository and tag prefix:\n\n```json\n{\n  \"AssetsRepo\": \"Azure/azure-sdk-assets\",\n  \"AssetsRepoPrefixPath\": \"\",\n  \"TagPrefix\": \"apitest/<ServiceName>/<package>\"\n}\n```\n\nThen, make a recording by starting test-proxy and running an API Scenario test:\n\n```bash\ntest-proxy start\noav run <your-scenario-file>.yaml -e <your-env>.json --testProxy http://localhost:5000 --testProxyAssets <your-assets-file>.json\n```\n\nAdditional examples include pushing recordings to a Git repository and restoring them.\n\nKEY TECHNICAL TERMS:\n1. API Scenario Test\n2. test-proxy\n3. assets.json\n4. traffic recording\n5. test-proxy start\n6. oav run\n7. test-proxy push\n8. test-proxy restore\n9. test-proxy reset\n10. Swagger consistency validation\n\n\n- [QuickStart.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/QuickStart.md): Quick Start with API Scenario Test using OAV\nThis document provides a step-by-step guide on using OAV (Open-Source API Validator) for API scenario testing. It starts by introducing OAV, a powerful tool for Swagger validation, API scenario testing, and example generation. The guide covers installing OAV, creating an AAD app, authoring API scenario files, and running tests. It also explains how to debug tests using Postman. The document provides YAML and JSON code examples for defining API scenarios and environment files.\n\n```yaml\n# Example API scenario file in YAML\nscope: ResourceGroup\nvariables:\n  configStoreName:\n    type: string\n    prefix: configstor\n\nscenarios:\n  - scenario: quickStart\n    description: Quick start with AppConfiguration ConfigurationStores\n    steps:\n      - step: Operations_CheckNameAvailability\n        exampleFile: ../examples/CheckNameAvailable.json\n```\n\n```json\n// Example env.json file\n{\n  \"subscriptionId\": \"<your subscription id>\",\n  \"location\": \"westcentralus\",\n  \"tenantId\": \"<AAD app tenantId>\",\n  \"client_id\": \"<your add client_id>\",\n  \"client_secret\": \"<your aad client_secret>\"\n}\n```\n\nAdditional code examples include API scenario files using operation-based steps and Postman collection files.\n\nKEY TECHNICAL TERMS:\n1. OAV (Open-Source API Validator)\n2. API Scenario Testing\n3. Swagger Validation\n4. AAD (Azure Active Directory) App\n5. Postman Collection\n6. API Scenario Definition\n7. Azure API Guidelines\n8. Traffic Schema Validation\n9. Azure Resource Manager (ARM)\n10. API Example Generation\n\n\n- [ResolveDependencies.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/ResolveDependencies.md): Resolve External Dependencies in API Scenarios\nThis document discusses how to resolve external dependencies in API scenarios, specifically in Azure API Scenarios. It introduces two key features: external operation references and ARM Template integration. External operation references allow calling cross-RP REST APIs before or between scenario steps. ARM Template integration enables creating external Azure resources and executing PowerShell or Azure CLI scripts. The document provides examples of creating a VM with API Scenarios, including using external operation references and ARM Templates.\n\nFor instance, to create a VM, you can use the following YAML configuration:\n\n```yaml\nprepareSteps:\n  - step: createVirtualNetwork\n    operationId: VirtualNetworks_CreateOrUpdate\n    readmeTag: ../../../../../../network/resource-manager/readme.md#package-2021-05\n    parameters:\n      virtualNetworkName: $(vmName)-VNET\n      parameters:\n        location: $(location)\n        properties:\n          addressSpace:\n            addressPrefixes:\n              - 10.0.0.0/16\n          subnets:\n            - name: $(vmName)-Subnet\n              properties:\n                addressPrefix: 10.0.0.0/24\n    outputVariables:\n      subnetId:\n        type: string\n        fromResponse: /properties/subnets/0/id\n```\n\nAnd here's an example of using ARM Template to provision resources:\n\n```json\n{\n  \"$schema\": \"https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#\",\n  \"contentVersion\": \"1.0.0.0\",\n  \"parameters\": {\n    \"vmName\": {\n      \"type\": \"string\",\n      \"defaultValue\": \"test\"\n    }\n  },\n  \"variables\": {\n    \"VNETName\": \"[concat(parameters('vmName'), '-VNET')]\",\n    \"SubnetName\": \"[concat(parameters('vmName'), '-Subnet')]\",\n    \"NSGName\": \"[concat(parameters('vmName'), '-NSG')]\",\n    \"PublicIPName\": \"[concat(parameters('vmName'), '-PublicIP')]\",\n    \"VMNicName\": \"[concat(parameters('vmName'), '-VMNic')]\"\n  },\n  \"resources\": [\n    {\n      \"name\": \"[variables('VNETName')]\",\n      \"type\": \"Microsoft.Network/virtualNetworks\",\n      \"location\": \"[resourceGroup().location]\",\n      \"apiVersion\": \"2015-06-15\",\n      \"dependsOn\": [],\n      \"tags\": {},\n      \"properties\": {\n        \"addressSpace\": {\n          \"addressPrefixes\": [\n            \"10.0.0.0/16\"\n          ]\n        },\n        \"subnets\": [\n          {\n            \"name\": \"[variables('SubnetName')]\",\n            \"properties\": {\n              \"addressPrefix\": \"10.0.0.0/24\"\n            }\n          }\n        ]\n      }\n    }\n  ]\n}\n```\n\nAdditional code examples include using Azure PowerShell or CLI scripts with ARM Template deployment scripts.\n\nKey technical terms and topics:\n\n1. API Scenarios\n2. External operation references\n3. ARM Template integration\n4. Azure PowerShell\n5. Azure CLI\n6. Cross-RP resources\n7. REST API\n8. Azure resources\n9. ARM Template deployment scripts\n10. Network RP\n11. Compute RP\n\n\n\n### references\n\n\n\n- [ApiScenarioDefinition.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/ApiScenarioDefinition.md): API Scenario Definition Reference for Azure REST API\nThe API Scenario Definition Reference provides a comprehensive guide to creating and managing API scenarios, which are used to define a series of steps that can be executed against Azure resources. An API scenario is defined in a YAML file, which includes a scope, variables, and a list of scenarios. Each scenario consists of a series of steps, which can be REST calls, ARM template deployments, or role assignments. The reference details the structure and fields of the API scenario definition file, including the scope, variables, scenarios, and steps. It also explains how to define REST call steps, ARM template steps, ARM deployment script steps, and role assignment steps.\n\nFor example, a simple API scenario definition file might look like this:\n\n```yaml\nscope: ResourceGroup\nvariables:\n  configStoreName:\n    type: string\n    prefix: configstor\n\nscenarios:\n  - scenario: quickStart\n    description: Quick start with AppConfiguration ConfigurationStores\n    steps:\n      - step: Operations_CheckNameAvailability\n        operationId: Operations_CheckNameAvailability\n        parameters:\n          checkNameAvailabilityParameters:\n            name: $(configStoreName)\n            type: Microsoft.AppConfiguration/configurationStores\n```\n\nThis example defines an API scenario with a scope of ResourceGroup, a variable `configStoreName`, and a single scenario `quickStart` with a step to check the name availability of a configuration store.\n\nThe document also provides details on the different types of steps that can be defined, including REST call steps, ARM template steps, ARM deployment script steps, and role assignment steps.\n\nSome key concepts include:\n\n*   **Scope**: The scope of the API scenario, which can be ResourceGroup, Subscription, Tenant, or None.\n*   **Variables**: Key-value pairs that can be used throughout the API scenario.\n*   **Scenarios**: A list of scenarios that define a series of steps to be executed.\n*   **Steps**: Individual steps within a scenario, which can be REST calls, ARM template deployments, or role assignments.\n\nKey technical terms and topics:\n\n1.  API Scenario\n2.  REST Call Step\n3.  ARM Template Step\n4.  ARM Deployment Script Step\n5.  Role Assignment Step\n6.  JsonPatchOp\n7.  JsonTestOp\n8.  Variables\n9.  Scope\n10. Azure REST API\n\nAdditional code examples are available in the document, covering topics such as defining variables, using JSON patch operations, and working with ARM templates. \n\nHere are some JsonPatchOp examples:\n\n```yaml\n- add: /properties/items\n  value: 1\n\n- remove: /properties/items/1\n\n- replace: /properties/location\n  value: \"eastus\"\n\n- copy: /properties/items2\n  from: /properties/items\n\n- move: /properties/items2\n  from: /properties/items\n```\n\n\n- [ErrorCodeReference.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/ErrorCodeReference.md): API Test Error Codes for Azure REST API\nThis document outlines error codes and examples for Azure REST API testing, focusing on ensuring consistency between service responses and provided examples. It details specific error types, such as INCORRECT_PROVISIONING_STATE, RESPONSE_MISSING_VALUE, RESPONSE_ADDITIONAL_VALUE, RESPONSE_INCONSISTENT_VALUE, and ROUNDTRIP_INCONSISTENT_PROPERTY. These errors help in identifying issues with API responses, including incorrect provisioning states, missing or additional values, inconsistent values, and property discrepancies between request and response. The document provides examples of these errors and their expected resolutions.\n\nExample of RESPONSE_MISSING_VALUE and RESPONSE_ADDITIONAL_VALUE:\n```diff\n{\n   \"properties\":{\n      \"targetType\":\"blobNfs\",\n      \"junctions\":[\n         {\n            \"namespacePath\":\"/blobnfs\"\n         }\n      ],\n      \"blobNfs\":{\n         \"target\":\"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/scgroup/providers/Microsoft.Storage/storageAccounts/blofnfs/blobServices/default/containers/blobnfs\",\n-         \"usageModel\":\"WRITE_WORKLOAD_15\"\n      }\n   }\n}\n```\n \nAdditional code examples are available for various error scenarios.\n\nKEY TECHNICAL TERMS:\n1. Provisioning State\n2. ARM RPC\n3. API Testing\n4. REST API\n5. Azure Resource Manager\n6. ProvisioningState\n7. API Responses\n8. Error Codes\n9. API Examples\n10. Azure SDK\n\n\n- [Runner.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/Runner.md): Azure API Scenario Runner Behavior and Implementation\nThis document explains the expected behavior of a runner that consumes API scenarios, including loading API scenario files via OAV, managing scopes, and executing steps defined in the scenario. The runner can load variables, manage resource groups, and run ARM template deployments. It must follow variable definitions, replace variables in parameters, and check response status codes and bodies. The document outlines the procedure for running API scenarios, including preparing steps, executing REST calls and ARM template deployments, and extracting output variables.\n\nThe runner can be implemented using the following code example:\n```typescript\n// Load the API scenario file\nconst scenarioDef = await loader.load(\n  \"Microsoft.ContainerService/stable/2020-12-01/scenarios/containerService.yaml\"\n);\n\n// Setup initial variable env\nconst env = new VariableEnv();\nenv.setBatch({\n  subscriptionId: \"__your_subs_id_\",\n  location: \"westus\",\n  SSH_PUBLIC_KEY: \"__public_key_ssh__\"\n});\n\n// Execute the API scenario\nconst runner = new ApiScenarioRunner({\n  jsonLoader: loader.jsonLoader,\n  env,\n  client: new ApiScenarioRestClient(getDefaultAzureCredential(), {})\n});\n\ntry {\n  for (const scenario of scenarioDef.scenarios) {\n    await runner.executeScenario(scenario);\n  }\n} catch (e) {\n  console.log(e.message, e.stack);\n} finally {\n  console.timeLog(\"TestLoad\");\n  await runner.cleanAllScope();\n}\n```\n\nAnother example of replacing variables in `parameters`:\n```typescript\n// Replace variables in parameters\nconst parameters = {\n  name: \"$(variableName)\",\n  location: \"$(location)\"\n};\n// Fill the request via parameter definition in swagger and parameter value in `parameters`.\n```\n\nNote that there are more code examples in the document that demonstrate how to manage resource groups, run ARM template deployments, and extract output variables.\n\nKEY TECHNICAL TERMS:\n\n1. API Scenario\n2. OAV (OpenAPI Validator)\n3. ARM Template Deployment\n4. Variable Environment\n5. Resource Group\n6. REST Call\n7. Long Running Request\n8. API Scenario Loader\n9. ApiScenarioRunner\n10. Swagger File Paths\n\n\n- [Variables.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/Variables.md): Variables in API Scenarios\nThis document explains the concept of variables in API scenarios, including their types, definition levels, and usage. Variables can be defined at different levels: runtime, global, scope, scenario, and step. They can be referenced using the syntax `$(variableName)` and can be replaced recursively. The document also describes conventions for parameter names in examples, location, and Arm Template deployments. For instance, in a step with a request parameter `param`, its value will be replaced with `$(param)` to reference the variable value. Similarly, a top-level `location` property will be replaced with the variable value if it exists.\n\nExample:\n```yaml\nvariables:\n  resourceName: level-1\n\nscenarios:\n  - description: Create some resource\n    variables:\n      resourceName: level-2\n    steps:\n      - step: Create resource\n        variables:\n          resourceName: level-3\n        exampleFile: ../examples/ResourceCreate.json\n```\n\n```json\n{\n  \"parameters\": {\n    \"userName\": {\n      \"type\": \"string\"\n    }\n  },\n  \"resources\": [],\n  \"outputs\": {\n    \"nameResult\": {\n      \"type\": \"string\",\n      \"value\": \"[concat('prefix/', parameters['userName'])]\"\n    }\n  }\n}\n```\n\nNote that there are additional examples in the document, including API scenario and Arm Template deployment examples.\n\nKEY TERMS:\n1. Variables\n2. API scenario\n3. Arm Template\n4. Runtime variables\n5. SecureString\n6. Recursive replacement\n7. Parameter naming convention\n8. Location convention\n9. Arm Template Deployment\n10. Variable types\n\n\n\n## code-gen\n\n\n\n- [configure-cli.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-cli.md): Azure CLI Readme Configuration Guide\nThis document provides a comprehensive guide on configuring readme files for Azure CLI code generation. It explains the common configuration, tag settings, and Swagger to SDK configurations. The guide covers various aspects, including basic information, tag configurations, Swagger to SDK settings, and Az dedicated configurations. It also provides examples of how to configure readme files for different scenarios, such as multi-api and multi-packages.\n\nTo generate Azure CLI code, you need to configure readme.az.md, readme.cli.md, and readme.python.md files. The readme.cli.md file contains common configurations for all command line tools, while readme.az.md is specific to Azure CLI. The readme.python.md file is required for Azure CLI, which calls Azure SDK for Python under the implementation layer.\n\nThe configuration files use YAML syntax to define settings for different tags, input files, and output folders. For example, you can specify a tag and its corresponding input files:\n\n``` yaml\n$(tag) == 'package-2019-12-01'\ninput-file:\n- Microsoft.Compute/stable/2019-12-01/compute.json\n- Microsoft.Compute/stable/2019-12-01/runCommands.json\n- Microsoft.Compute/stable/2019-12-01/gallery.json\n```\n\nYou can also configure Swagger to SDK settings:\n\n``` yaml\n$(swagger-to-sdk)\nswagger-to-sdk:\n  - repo: azure-cli-extensions\n  - ...\n```\n\nThe Az dedicated configurations are defined in readme.az.md, which includes settings for Azure CLI extensions and main modules:\n\n``` yaml\n$(az) && $(target-mode) != 'core'\naz:\n    extensions: communication\n    namespace: azure.mgmt.communication\n    package-name: azure-mgmt-communication\naz-output-folder: $(azure-cli-extension-folder)/src/communication\npython-sdk-output-folder: \"$(az-output-folder)/azext_communication/vendored_sdks/communication\"\n```\n\nKey topics and technical terms:\n\n*   readme.az.md\n*   readme.cli.md\n*   readme.python.md\n*   Azure CLI\n*   Swagger to SDK\n*   Az configurations\n*   Multi-api\n*   Multi-packages\n*   Autorest\n\nThe document also mentions that for advance usage of CLI Codegen, one can refer to [autorest.az doc](https://github.com/Azure/autorest.az/tree/master/doc). \n\nAdditional code examples are available in the document, covering various scenarios and configurations. \n\nExamples of commands to run autorest for code generation:\n\n```bash\nautorest --az --use=@autorest/az@latest /home/qiaozha/code/azure-rest-api-specs/specification/storage/resource-manager/readme.md --azure-cli-extension-folder=../azure-cli-extensions\n```\n\n\n- [configure-go-sdk.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-go-sdk.md): Readme Configuration Guide for Azure SDK for Go\nThis document provides a comprehensive guide on configuring readme files for Azure SDK for Go code generation. It covers basic information configuration, tag definitions, Swagger to SDK settings, and Go-specific configurations. The guide explains how to generate and test Go SDKs using the configured readme files. It also includes code examples for generating Go SDKs and testing them locally.\n\nThe document outlines the necessary configurations for generating Go SDKs, including setting the package title, description, and tags. It also explains how to configure Swagger files for specific clients and generate SDKs using the `autorest` command. Additionally, it provides steps for testing generated Go SDKs locally.\n\nExample configurations for readme files:\n```yml\ntitle: xxxxConfigurationClient\ndescription: xxxx Configuration Client\nopenapi-type: arm\ntag: package-xxxx-xx-xx\n```\n\n```yml\n## Go\n\nThese settings apply only when `--go` is specified on the command line.\n\n```yaml $(go) && $(track2)\nlicense-header: MICROSOFT_MIT_NO_VERSION\nmodule-name: sdk/resourcemanager/agrifood/armagrifood\nmodule: github.com/Azure/azure-sdk-for-go/$(module-name)\noutput-folder: $(go-sdk-folder)/$(module-name)\nazure-arm: true\nmodule-version: 0.1.0\n```\nExtra code examples include configurations for Swagger to SDK and testing generated Go SDKs locally.\n\nKEY TECHNICAL TERMS:\n\n* Azure SDK for Go\n* Readme configuration\n* Swagger to SDK\n* Go SDK generation\n* Autorest command\n* Module name configuration\n* Output folder configuration\n* Azure arm configuration\n* Module version configuration\n\n\n- [configure-python-sdk.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-python-sdk.md): Readme Configuration Guide for Python SDK\nThis document provides a configuration guide for generating Python SDKs using Azure REST API specifications. It explains how to configure readme files to make them available for Python SDK code generation. The guide covers basic information configuration, tag definitions, and Swagger to SDK settings. It also provides examples of how to configure multi-API support, batch processing, and output folders for generated SDKs.\n\nThe document outlines the structure and syntax for readme files, including how to specify package information, tags, and input files for Swagger code generation. It also describes how to configure settings for Python SDK generation, such as namespace, output folder, and package version.\n\nFor example, to configure basic package information, you can use the following YAML code:\n``` yaml\ntitle: AppconfigurationConfigurationClient\ndescription: Appconfiguration Configuration Client\nopenapi-type: arm\ntag: package-2019-10-01\n```\nAdditionally, you can configure multi-API support using the `batch` section:\n``` yaml\nbatch:\n  - tag: package-2020-06-01-only\n  - tag: package-2020-05-01-only\n  - multiapiscript: true\n```\nThis document provides detailed information on configuring readme files for Python SDK generation, including code examples and technical terms.\n\nCODE EXAMPLES: \n- Basic Information Configuration: \n``` yaml\ntitle: AppconfigurationConfigurationClient\ndescription: Appconfiguration Configuration Client\nopenapi-type: arm\ntag: package-2019-10-01\n```\n- Multi-API Support Configuration:\n``` yaml\nbatch:\n  - tag: package-2020-06-01-only\n  - tag: package-2020-05-01-only\n  - multiapiscript: true\n```\n\nKEY TECHNICAL TERMS:\n\n* Azure REST API\n* Python SDK\n* Swagger\n* Autorest\n* Multi-API support\n* Batch processing\n* Code generation\n* OpenAPI\n* API versions\n\n\n- [configure-typescript-sdk.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-typescript-sdk.md): Readme Configuration Guide for Azure SDK for Javascript (Typescript)\nThis document provides a configuration guide for Azure SDK for Javascript (Typescript) code generation. It explains how to configure readme files to make them available for the Azure SDK. The guide covers basic information configuration, tag configuration, swagger to SDK configuration, and Typescript configuration. It also provides examples of how to configure multiple packages and tags.\n\nTo configure the readme file, start by specifying basic package information such as title, description, and tag. For example:\n``` yaml\ntitle: xxxxConfigurationClient\ndescription: xxxx Configuration Client\nopenapi-type: arm\ntag: package-xxxx-xx-xx\n```\nThen, configure the tag by specifying the input files for a specific tag. For instance:\n``` yaml\n$(tag) == 'package-2019-12-01'\ninput-file:\n- Microsoft.Compute/stable/2019-12-01/compute.json\n- Microsoft.Compute/stable/2019-12-01/runCommands.json\n- Microsoft.Compute/stable/2019-12-01/gallery.json\n```\nThe document also provides an example of Typescript configuration:\n```yaml\ntypescript:\n  azure-arm: true\n  package-name: \"@azure/arm-apimanagement\"\n  output-folder: \"$(typescript-sdks-folder)/sdk/apimanagement/arm-apimanagement\"\n  clear-output-folder: true\n  generate-metadata: true\n```\nThis guide also mentions that Azure SDK for Javascript (Typescript) doesn't support multi-api and only supports single api packages.\n\nSome additional code examples are available in the document, including configurations for multi-packages and different tags.\n\nHere are some code examples:\n``` yaml\n$(swagger-to-sdk)\nswagger-to-sdk:\n  - repo: azure-sdk-for-js\n  - ...\n```\n```yaml\n$(typescript) && !$(profile)\ntypescript:\n  package-name: \"@azure/arm-features\"\n  output-folder: \"$(typescript-sdks-folder)/sdk/features/arm-features\"\n  clear-output-folder: true\n```\n\nKEY TECHNICAL TERMS:\n\n* Azure SDK for Javascript (Typescript)\n* Swagger to SDK\n* Typescript Configuration\n* Multi-api\n* Multi-packages\n* Autorest\n* azure-sdk-for-js\n* Typescript-sdks-folder\n* openapi-type\n* Tag configuration\n\n\n\n## onboard-dpg-in-sdkautomation\n\n\n\n- [Integrate-dpg-and-apiview-in-sdk-automation-pipeline.md](https://raw.githubusercontent.com/Azu

{"metadata":{},"top_logprobs":0,"temperature":1,"top_p":1,"service_tier":"default","previous_response_id":"resp_002a07ca2295fc9a006994d95fbcb881938363c167d5326adc","model":"gpt-4.1","reasoning":{},"background":false,"text":{"format":{"type":"text"},"verbosity":"medium"},"tools":[{"type":"mcp","server_label":"api-specs","server_url":"https://gitmcp.io/Azure/azure-rest-api-specs","require_approval":"always"}],"tool_choice":"auto","truncation":"disabled","id":"resp_002a07ca2295fc9a006994d967e364819392791e48d158c8e5","object":"response","status":"completed","created_at":1771362664,"completed_at":1771362678,"error":null,"incomplete_details":null,"output":[{"type":"mcp_call","id":"mcp_002a07ca2295fc9a006994d96a1f4c81938ceb190d03f6c40f","agent_reference":{"type":"agent_reference","name":"cs-e2e-tests-client","version":"1"},"response_id":"resp_002a07ca2295fc9a006994d967e364819392791e48d158c8e5","server_label":"api-specs","name":"fetch_azure_rest_api_docs","arguments":"{}","output":"# Azure/azure-rest-api-specs/documentation Documentation\nBelow is a structured llms.txt index of Markdown files extracted from the /documentation folder. Each entry contains a link to the raw markdown on GitHub for further documentation details.\n\n\n## Root Files\n\n\n\n- [Breaking changes guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Breaking%20changes%20guidelines.md): Azure REST API Version Change Guide\nThis document provides guidance to Azure Service teams on making changes to REST APIs, focusing on updating API versions to maintain backwards compatibility. It supplements the official Microsoft REST API guidelines and outlines scenarios that require a new API version, including removing or renaming properties, changing property types, and adding new required properties. The guide also covers non-breaking changes, such as adding new APIs, read-only fields, and bug fixes. Understanding these guidelines is crucial for ensuring smooth API evolution.\n\nFor example, if a property \"foo\" was a boolean in v1 but is changed to a string, the API version must be updated:\n```json\n// v1\n{\n  \"foo\": true\n}\n// v2\n{\n  \"foo\": \"string\"\n}\n```\nSimilarly, adding a new required property to the request body is a breaking change:\n```json\n// v1\n{\n  \"name\": \"resource\"\n}\n// v2\n{\n  \"name\": \"resource\",\n  \"newProperty\": \"requiredValue\"\n}\n```\nAdditional examples include changes to property names, enum values, and API behavior.\n\nKEY TECHNICAL TERMS:\n\n1. Backwards compatibility\n2. Breaking changes\n3. API versioning\n4. REST API guidelines\n5. Property type changes\n6. Enum changes\n7. API deprecation policy\n8. Resource naming rules\n9. Non-breaking changes\n10. API evolution\n\n\n- [BreakingChange-Oad-Rules-Mapping.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/BreakingChange-Oad-Rules-Mapping.md): Azure REST API Breaking Change and OAD Rules Mapping\nThis document outlines the relationship between OpenAPI Diff (OAD) rules and Azure's breaking change policy for REST APIs. It provides a table mapping OAD rules to breaking change categories, detailing changes such as removed or added parameters, changed response codes, and modified operation IDs. The rules are identified by IDs (e.g., 1002-1046) and describe specific changes like protocol support, request/response body formats, and property additions/removals. Understanding these rules helps in assessing the impact of API changes on existing clients and ensuring backward compatibility. For instance, rules like [1002 - ProtocolNoLongerSupported](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1002.md) and [1038 - AddedPath](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1038.md) illustrate how changes are categorized.\n\nExample of OAD rule: \n- [1002 - ProtocolNoLongerSupported](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1002.md): Describes a breaking change when a protocol is no longer supported.\n\nAdditional code examples are available throughout the document, detailing various rules such as [AddedEnumValue](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1020.md) and [TypeFormatChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1023.md).\n\nKEY TECHNICAL TERMS:\n1. OAD Rules\n2. Breaking Change Policy\n3. Azure REST API\n4. OpenAPI Diff\n5. API Versioning\n6. Backward Compatibility\n7. REST API Changes\n8. API Breaking Changes\n9. OpenAPI Specifications\n10. Azure API Guidelines\n\n\n- [FAQ.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/FAQ.md): Azure API Spec PR Review FAQ\nThis document provides answers to frequently asked questions during Azure API spec PR review. It covers topics such as onboarding to API spec PR review process, fixing validation failures, generating SDKs, documents, and examples from API specs. The document is divided into sections, each addressing a specific question. For instance, new users can start by referring to the [API specs document](https://eng.ms/docs/products/azure-developer-experience/design/api-specs/api-specs#create-your-rest-api-definition) for an introduction. To fix validation failures, refer to the [validation table](#validation) which lists common issues and their fixes.\n\n```markdown\n// Example of fixing validation failure\n| Validation | Description | How to fix |\n| --- | --- | --- |\n| Model Validation | Model validation enforces correctness between example and swagger.  | [Fix Model Validation](https://aka.ms/ci-fix#model-validation) |\n```\n\nThe document also provides resources for [generating SDKs from API specs](https://eng.ms/docs/products/azure-developer-experience/develop/sdk-generate) and [creating documentation](https://eng.ms/docs/products/azure-developer-experience/design/api-docs).\n\nAdditional code examples are available in the document, including [Swagger Example Generation](https://github.com/Azure/oav/blob/develop/documentation/example-generation.md).\n\n## Key Technical Terms and Topics:\n\n1. API Specs\n2. Swagger\n3. Validation Failure\n4. SDK Generation\n5. Documentation Generation\n6. Example Generation\n7. Model Validation\n8. Lint Diff\n9. Breaking Change\n10. Avocado\n\nNote that I have only extracted key terms and concepts directly mentioned in the document and provided a concise summary of the content.\n\n\n- [Getting started with OpenAPI specifications.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Getting%20started%20with%20OpenAPI%20specifications.md): OpenAPI Specification for Azure REST API\nThe OpenAPI Specification, formerly known as Swagger Specification, is a format for describing REST APIs. It allows you to describe your entire API, including available endpoints, operations, parameters, authentication methods, and more. Currently, Azure supports OpenAPI Specification 2.0 or Swagger V2.0. To get started, you can refer to helpful resources such as the GitHub flow, contributing guidelines, Azure REST API guidelines, and OpenAPI Style Guide. The specification includes essential information like endpoints, operations, parameters, and authentication methods. For example, you can describe available endpoints like `/users` and operations on each endpoint like `GET /users` and `POST /users`. \n\nThe structure of a Swagger specification and sample files are provided for reference. Additionally, there are guidelines for authoring good Swagger descriptions, validation tools, and breaking changes.\n\nExample:\n```json\n// Sample Swagger specification\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Your Service Name\",\n    \"description\": \"Your service description\",\n    \"version\": \"1.0.0\"\n  },\n  \"paths\": {\n    \"/users\": {\n      \"get\": {\n        \"summary\": \"Get users\",\n        \"responses\": {\n          \"200\": {\n            \"description\": \"OK\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nThere are also additional examples in the `samplefiles` directory.\n\nKEY TECHNICAL TERMS:\n1. OpenAPI Specification\n2. Swagger Specification\n3. REST APIs\n4. Azure REST API guidelines\n5. OpenAPI Style Guide\n6. Swagger V2.0\n7. API description format\n8. Endpoints\n9. Operations\n10. Validation tools\n\n\n- [Getting-started-with-TypeSpec-specifications.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Getting-started-with-TypeSpec-specifications.md): What is a TypeSpec Specification in Azure REST API\nTypeSpec is a versatile language for describing cloud service APIs and generating API description languages, client and service code, documentation, and other related assets. It provides highly extensible core language primitives that can describe API structures common among REST, GraphQL, gRPC, and other protocols. Within the azure-rest-api-specs repository, TypeSpec serves as the source to generate corresponding OpenAPI 2.0 (swagger) API documentation. To get started with TypeSpec, one should include a `tspconfig.yaml` file, an examples folder, and follow specific folder structure guidelines. For instance, the TypeSpec folder name for ARM services should end with `.Management`. A `tspconfig.yaml` file for ARM template may look like the following:\n\n```yml\n# tspconfig.yaml example\n```\nFor Data-Plane, a `tspconfig.yaml` starting template is provided. \n```yml\n# tspconfig.yaml example for Data-Plane\n```\nThe document also provides detailed information on setting up a local environment, folder structure, and regenerating SDK projects.\n\nAdditional code examples include setting up a new TypeSpec project and regenerating SDK projects.\n\nKEY TECHNICAL TERMS:\n- TypeSpec\n- Azure REST API guidelines\n- OpenAPI 2.0 (swagger)\n- tspconfig.yaml\n- typespec-autorest\n- ARM template\n- Data-Plane\n- typespec-core\n- typespec-resource-manager\n- API description languages\n\n\n- [Semantic-and-Model-Violations-Reference.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/Semantic-and-Model-Violations-Reference.md): Semantic and Model Violations Reference for Azure REST API\nThis document lists automated rules validated against Swagger specs using the OAV tool, providing error information, descriptions, and tips for fixing violations. It covers various aspects, including validation errors, warnings, and rule descriptions.\n\nThe document provides a comprehensive list of potential issues that can arise when creating or updating Swagger specifications for Azure REST APIs. These issues range from simple errors like invalid content types or missing required properties to more complex problems like circular inheritance or semantic validation errors.\n\nTo effectively use this document, one should first understand the nature of the error or warning they are encountering. For instance, if there's an \"INVALID_CONTENT_TYPE\" error, the document advises fixing the content-type to one of the supported values. Similarly, for a \"MISSING_PATH_PARAMETER_DECLARATION\" error, one should add the declaration or remove the definition of the parameter.\n\nHere is an example of how to address a common issue:\n\n```json\n// Example of fixing INVALID_TYPE error\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\"\n    }\n  },\n  \"required\": [\"name\"]\n}\n```\n\nSome key topics and terms extracted from the document include:\n\n1. **Validation Errors**: These are errors that occur when the Swagger specification fails validation, such as missing required properties, invalid types, or semantic validation errors.\n2. **INVALID_REFERENCE**: This error occurs when a reference in the Swagger spec is invalid.\n3. **CIRCULAR_INHERITANCE**: This happens when a schema inherits from itself.\n4. **MISSING_PATH_PARAMETER_DECLARATION**: A path parameter is declared but not defined.\n5. **INVALID_PARAMETER_COMBINATION**: Body and formData parameters are mutually exclusive.\n6. **DUPLICATE_OPERATIONID**: Multiple operations with the same operationId are not allowed.\n7. **SEMANTIC_VALIDATION_ERROR**: Errors occur during semantic validation of the Swagger spec.\n\nBy understanding and addressing these issues, developers can ensure their Swagger specifications are accurate, complete, and follow best practices for Azure REST APIs. \n\nExamples of errors and fixes:\n\n- **INVALID_TYPE**: Expected type 'int' but found type 'string'.\n- **MISSING_REQUIRED_PROPERTY**: Missing required property 'name'.\n\nThe document serves as a critical resource for developers to identify, resolve, and prevent common errors in Swagger specifications for Azure REST APIs.\n\n\n- [SwaggerValidationTools.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/SwaggerValidationTools.md): Validation Tools for Azure REST API Specifications\nThis document provides information on tools available for validating Azure REST API specifications against accepted guidelines. It lists various tools that can be used locally to ensure specifications conform to guidelines before sending a pull request. The tools include Linter Validator, Static Validator (Semantic), Static Validator (Model), and Swagger diff tool. To use these tools, one needs to install Node.js (7.10.0 or greater) and then install the required tools using npm. The document provides commands for installing and using each tool, such as `autoRest`, `oav validate-spec`, `oav validate-example`, and `oad compare`. Additionally, it mentions a suppression process for Microsoft FTEs to request suppression of false positive errors.\n\nExample usage:\n- `npm install -g autorest`\n- `autoRest <path to readme.md> --azure-validator=true`\n\nThe document also mentions other code examples for `oav validate-spec` and `oad compare`.\n\nEXTRA EXAMPLES AVAILABLE: Swagger validation, suppression process.\n\nKEY TERMS:\n- Azure REST API\n- Validation tools\n- Linter Validator\n- Static Validator (Semantic)\n- Static Validator (Model)\n- Swagger diff tool\n- Node.js\n- npm\n- autorest\n- oav\n- oad\n- suppression process\n\n\n- [ci-fix.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/ci-fix.md): CI Fix Guide for Azure REST API Specs\nThis guide provides detailed troubleshooting instructions for automated validation tooling checks running on Azure REST API specs PRs. It covers various checks, including CredScan, PoliCheck, SDK Validation, Swagger APIView, Swagger ApiDocPreview, Swagger Avocado, Swagger BreakingChange, Swagger LintDiff, Swagger Lint(RPaaS), Swagger ModelValidation, Swagger PrettierCheck, Swagger SemanticValidation, Spell Check, and TypeSpec Validation. The guide also explains the suppression process and lists obsolete checks.\n\nTo troubleshoot issues with these checks, follow the steps outlined in the guide. For example, to run `oad` locally for Swagger BreakingChange checks, use the following command:\n\n```powershell\nnpm install -g @azure/oad\noad compare <old-spec-path> <new-spec-path>\n```\n\nSimilarly, to validate examples with Swagger ModelValidation, use:\n\n```powershell\nnpm install -g oav\noav validate-example <openapi-spec-path>\n```\n\nThe guide also provides information on how to update spec files using Prettier and how to add words to the override list for spell checking.\n\nKEY TECHNICAL TERMS:\n\n1. Azure REST API specs\n2. Automated validation tooling\n3. Swagger APIView\n4. Swagger BreakingChange\n5. Swagger LintDiff\n6. TypeSpec Validation\n7. PrettierCheck\n8. SemanticValidation\n9. ModelValidation\n10. Spell Check\n\nThese terms are crucial for understanding and troubleshooting the various checks and validations involved in the Azure REST API specs PR build process.\n\n\n- [creating-swagger.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/creating-swagger.md): AutoRest Swagger Conventions and Extensions\nThis document explains the conventions and extensions used by AutoRest in processing Swagger to produce client libraries. It covers various aspects of Swagger, including Info Object, Host, Schemes, Consumes/Produces, Paths, Path Item, Operation and OperationId, Parameters, Responses, Model Types, Model Inheritance, Polymorphic Response Models, Resource Flattening, Enums, Paging, URL Encoding, Long Running Operations, and Global Parameters. The document provides a comprehensive guide on how to use Swagger with AutoRest to generate client libraries.\n\nFor example, consider the following Swagger definition:\n```json5\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"MyClientName\",\n  }\n}\n```\nThis will generate a client library with a class named `MyClientName`.\n\nAnother example is the use of `x-ms-enum` extension:\n```json5\n\"accountType\": {\n  \"type\": \"string\",\n  \"enum\": [\n    \"Standard_LRS\",\n    \"Standard_ZRS\",\n    \"Standard_GRS\",\n    \"Standard_RAGRS\",\n    \"Premium_LRS\"\n  ],\n  \"x-ms-enum\": {\n    \"name\": \"AccountType\",\n    \"modelAsString\": false\n  }\n}\n```\nThis will generate an enum type in C#.\n\nKEY TECHNICAL TERMS:\n\n1. AutoRest\n2. Swagger\n3. OpenAPI Specification\n4. x-ms-enum\n5. x-ms-pageable\n6. x-ms-long-running-operation\n7. Resource Flattening\n8. Model Inheritance\n9. Polymorphic Response Models\n10. URL Encoding\n\nSome other code examples available in document:\n- Model Inheritance \n- Paging with x-ms-pageable \n- Long Running operation \n- Enums with x-ms-enum\n\n\n- [directory-structure.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/directory-structure.md): Azure REST API Specifications Directory Structure\nThe `specification` directory in the Azure REST API specifications repository contains the directory structure and guidelines for organizing service specifications. It is divided into team folders, each containing TypeSpec specifications, resource manager, and data-plane services. The structure reflects key concepts such as services, service groups, and uniform versioning. Teams can organize their services under `resource-manager` or `data-plane` folders, following specific naming conventions and folder layouts. For example, a service folder might be located at `specification/<azureTeam>/resource-manager/<RPNS>/<service>`, where `<azureTeam>` is the team name, `<RPNS>` is the Resource Provider namespace, and `<service>` is the service name.\n\n```markdown\nExample of service folder structure:\n- specification\n  - <azureTeam>\n    - resource-manager\n      - <RPNS>\n        - <service>\n          - stable\n            - <apiVersion>\n          - preview\n            - <apiVersion-preview>\n```\n\nThe document also provides guidelines for naming conventions, migrating from legacy directory structures, and deprecated directory structures.\n\nAdditional code examples and information can be found in the [TypeSpec directory structure](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md) and [API versioning guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning).\n\nKEY TERMS:\n1. TypeSpec\n2. Resource Provider Namespace (RPNS)\n3. Service group\n4. Grouping directory\n5. Uniform versioning\n6. AutoRest config\n7. OpenAPI specifications\n8. Azure Team\n9. Data-plane services\n10. Resource Manager services\n\n\n- [glossary.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/glossary.md): Glossary of Terms for Azure REST API Specifications\nThis document defines key terms used in the Azure REST API specifications, including grouping directory, resource type, service, service group, and uniform versioning. A grouping directory is a root folder for data-plane service folders, where each service versions uniformly but independently of others. A service is a set of operation endpoints with a cohesive, uniformly versioned experience for customers. A service group is a set of services sharing a common ARM Resource Provider namespace. The document explains how services and service groups are structured and related to ARM Resource Provider namespaces.\n\nFor example, a service can be found in a path like `specification/containerservice/resource-manager/Microsoft.ContainerService/aks`, and a service group can be seen in `specification/containerservice/resource-manager/Microsoft.ContainerService`. \n\nAdditional code examples illustrate service and service group structures, such as [`specification/containerservice/resource-manager/Microsoft.ContainerService/aks`] and [`specification/containerservice/resource-manager/Microsoft.ContainerService`].\n\nCODE EXAMPLES:\n- Service path: `specification/<azureTeamName>/resource-manager/<RPNS>/<service>`\n- Service group path: `specification/<azureTeamName>/resource-manager/<RPNS>`\n\nEXTRA EXAMPLES: Directory structure and versioning examples are also provided.\n\nKEY TERMS:\n1. Grouping directory\n2. Resource type\n3. Service\n4. Service group\n5. Uniform versioning\n6. ARM Resource Provider namespace\n7. Resource Provider (RP) namespace\n8. Data-plane service\n9. Directory structure\n10. Uniform versioning article\n\n\n- [openapi-authoring-automated-guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/openapi-authoring-automated-guidelines.md): Azure/azure-rest-api-specs Documentation\nNo summary available\n\n\n- [openapi-authoring-manual-guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/openapi-authoring-manual-guidelines.md): ** OpenAPI Specifications Authoring Manual Guidelines\n** \nThis document outlines the manual guidelines for authoring OpenAPI (Swagger) specifications. It provides a set of rules to ensure that the specifications are accurate, consistent, and follow best practices. The guidelines are categorized into errors and warnings, with errors requiring immediate attention before sending a pull request for review. The rules cover aspects such as resource model naming, required parameters, read-only properties, and documentation quality. Authors are expected to conform to these guidelines to ensure that the OpenAPI specifications correctly represent the underlying REST API. For example, a resource model name MUST be the same as the singular form of the resource type, and required parameters MUST be accurately labeled as \"required\": true in the OpenAPI specification. Additionally, descriptions MUST NOT contain spelling errors, grammatical errors, or dummy texts.\n\n**CODE EXAMPLES:** \n- Resource Model name: `VirtualMachine` (singular form) instead of `virtualMachines`.\n- Required parameters: `parameters: [ { \"name\": \"resourceGroupName\", \"required\": true } ]`.\n\nThere are more code examples available in the document that demonstrate how to apply these guidelines.\n\n**KEY TECHNICAL TERMS AND TOPICS:**\n\n1. OpenAPI Specifications\n2. Swagger\n3. Resource Model\n4. x-ms-parameter-location\n5. x-ms-mutability\n6. x-ms-enum\n7. External Documentation\n8. OData parameters\n9. API Documentation\n10. REST API Specs\n\n\n- [swagger-accuracy-report.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-accuracy-report.md): Service Contract Accuracy Report for Azure REST API\nThe Service Contract Accuracy Report ensures that service contracts accurately reflect true service behavior. This report is generated using RESTler and OAV tools, which test all service operations and compare actual requests and responses against the contract. To improve API coverage, users can download RESTler configuration files, modify them, and run RESTler locally. The process involves creating an authentication script, modifying configuration files (dictionary, annotation, and engine settings), and testing changes locally. After making improvements, the modified configuration files can be uploaded to the azure-rest-api-specs repository to re-run the Service Contract Accuracy report. \n\nExample authentication script for obtaining AAD tokens:\n```sh\n#!/bin/bash\n\nfind . -name 'token.json' -depth 1 -mtime -1h | grep . &> /dev/null || az account get-access-token --scope <AAD Scope for the service>> token.json\n\ntoken=Sanitized -r '.accessToken' token.json)\n\necho \"{'user1':{}, 'user2':{}}\"\necho \"Authorization: bearer ${token}\"\necho \"Authorization: shadow_unit_test_token\"\n```\n\nExample command for running RESTler locally:\n>Restler.exe test --dictionary_file dict.json --grammar_file grammar.py --settings engine_settings.json --token_refresh_command \"/local-scripts/get-token.sh\" --token_refresh_interval 60\n\nThere are additional code examples for dictionary, annotation, and engine settings configuration.\n\nKEY TECHNICAL TERMS:\n1. RESTler\n2. OAV\n3. Service Contract Accuracy Report\n4. Swagger specification\n5. Azure CLI\n6. AAD authentication\n7. RESTler configuration files\n8. Traffic validation pipeline\n9. Engine settings\n10. API coverage\n\n\n- [swagger-authoring-descriptions.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-authoring-descriptions.md): ** Writing Effective Descriptions in Swagger 2.0\n** \nThis document provides guidelines for authoring high-quality descriptions in Swagger 2.0, which become the baseline public Azure REST API documentation. It emphasizes the importance of well-crafted descriptions, offering tips and tools to ensure consistency and professionalism. The guide covers basic rules, such as starting with a capital letter, using correct grammar and spelling, and documenting HTTP status codes. It also suggests good practices, including previewing content, reviewing style guides, and using tools like Grammarly. The descriptions are used not only on learn.microsoft.com but also in client SDKs, Swagger UI, and other REST documentation tools.\n\n**CODE EXAMPLES:** \nNo specific code examples are provided in the document, but it mentions that descriptions can be written in a style similar to this: \"Gets a GitHub-Flavored Markdown (GFM) formatted document that contains the current release notes.\" \n\nAdditional examples of well-written descriptions can be found throughout the document.\n\n**KEY TECHNICAL TERMS AND TOPICS:** \n1. Swagger 2.0\n2. Azure REST API\n3. AutoRest\n4. OpenAPI\n5. Grammarly\n6. Swagger UI\n7. IntelliSense\n8. Microsoft Writing Style Guide\n9. Azure-specific Microsoft Cloud Style Guide\n10. Open Publishing (OP) DocFX tool\n\n\n- [swagger-checklist.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-checklist.md): Swagger Checklist for Microsoft Azure\nThis document provides a checklist for developing Swagger specifications for Microsoft Azure. It outlines requirements and guidelines for creating and validating Swagger documents, including automated and manual rules. The Azure developer experience team has created tools to validate Swagger specifications, such as the AutoRest OpenAPI Validator and Swagger Model Validator. These tools help ensure that Swagger documents meet the necessary requirements and are free of errors. The checklist is continuously updated to reflect issues uncovered during Swagger specification reviews. To get started, developers can install the validation tools on their development machines and use them to validate their Swagger documents as they build them. The [\"x-ms-examples\"](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) extension is used to integrate test examples into Swagger documents.\n\nExample of using AutoRest OpenAPI Validator:\n```bash\n# Activate the OpenAPI validator with --azure-validator\n```\nExample of using Swagger Model Validator with [\"x-ms-examples\"](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) extension:\n```json\n// Sample test examples for this extension can be found in the Redis Cache Swagger\n// https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json\n```\n\nAdditional code examples are available in the [Redis Cache Swagger](https://github.com/Azure/azure-rest-api-specs/blob/master/arm-redis/2016-04-01/swagger/redis.json).\n\nKEY TECHNICAL TERMS:\n\n* Swagger\n* OpenAPI\n* AutoRest OpenAPI Validator\n* Swagger Model Validator\n* x-ms-examples extension\n* Azure REST API\n* API validation\n* Swagger specification\n* Azure developer experience team \n* Validation tools\n\n\n- [swagger-extensions.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/swagger-extensions.md): AutoRest Extensions for OpenAPI 2.0 Documentation\nThis document provides information on AutoRest extensions for OpenAPI 2.0, a specification used for generating client libraries for Azure REST APIs. The document references an external link for detailed information on AutoRest extensions, which enable features such as adding custom headers, supporting polymorphism, and more. It appears to be a brief introduction to the concept, pointing to the main documentation source at https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md. To learn more about using AutoRest extensions, one should visit the provided GitHub link for comprehensive details and usage guidelines.\n\nCODE EXAMPLES:\nNo code examples are directly provided in the given document content.\n\nADDITIONAL EXAMPLES NOTE: The document does not provide additional code examples beyond the reference link.\n\nKEY TECHNICAL TERMS:\n- AutoRest\n- OpenAPI 2.0\n- Azure REST APIs\n- AutoRest extensions\n\n\n- [typespec-end-to-end-scenarios.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/typespec-end-to-end-scenarios.md): TypeSpec End-to-End Scenarios\nThis document outlines the end-to-end scenarios for TypeSpec, a tool for generating SDKs from API specifications. It covers four main user scenarios: TypeSpec project scaffolding, SDK code generation, inner dev loop SDK generation, and outer dev loop. The document provides flowcharts and details for each scenario, including the steps involved, scripts used, and remaining tasks. It aims to provide a smooth process for developers to work with TypeSpec and generate SDKs.\n\nThe document describes the following key scenarios:\n\n*   TypeSpec project scaffolding: creating a new TypeSpec project using `tsp init` and generating swagger examples.\n*   SDK code generation: generating SDK code using TypeSpec.\n*   Inner dev loop SDK generation: generating SDKs locally on a developer's machine.\n*   Outer dev loop: shepherding TypeSpec documents through the Azure/azure-rest-api-specs repository and its dependency repos/branches to different language SDK repos.\n\nExample code:\n```mermaid\nflowchart TD\nclassDef highlight fill:#ffd700\nclassDef grey fill:#CCCCCC,color:#555555;\nUser((::)) --> |Develop in rest-api repo|A[Clone rest-api repo]\nUser((::)) --> |Develop in custom service repo|B1[1.2 `tsp init https://aka.ms/azure-init`]\nB1-->D\nA --> B[1.1 Create folder structure per spec ]\nB --> C[\"1.2 `tsp init https://aka.ms/azure-init`<br>delete package.json in project folder\"]\nC --> D[...iterate on *.tsp specs]\nD ---> |Loop|F\nD --> E[\"1.3 generate swagger examples\n(need a new script)\"]\nE --> F[\"tsp compile . (generate swaggers)\"]\nF --> G1[Copy specs files into rest-api repo]\nG1 --> G2[Optionally: Adopt shift-left pipeline]\nG2--> G\nF --> G[create a spec PR]\n```\nAdditional code examples include PowerShell scripts for TypeSpec project processing, such as `TypeSpec-Project-Process.ps1`, `TypeSpec-Project-Sync.ps1`, and `TypeSpec-Project-Generate.ps1`.\n\nKey technical terms and topics:\n\n1.  TypeSpec\n2.  Azure REST API specs\n3.  SDK generation\n4.  Inner dev loop\n5.  Outer dev loop\n6.  TypeSpec project scaffolding\n7.  TypeSpec project processing scripts (`TypeSpec-Project-Process.ps1`, `TypeSpec-Project-Sync.ps1`, `TypeSpec-Project-Generate.ps1`)\n8.  SDK code generation\n9.  API view generation\n10. CI/CD pipeline\n\n\n- [typespec-rest-api-dev-process.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/typespec-rest-api-dev-process.md): Azure Rest API and SDK Development with TypeSpec\nThis document outlines the process for developing Azure Rest APIs and SDKs using the TypeSpec language. It covers setting up the repository, creating a new TypeSpec project, preparing and submitting a Pull Request, and generating or refreshing SDK code. The guide assumes development in the `azure-rest-api-specs` and `azure-rest-api-specs-pr` repositories. Prerequisites include Node.js LTS version 18 or above and installing required packages with `npm ci`. TypeSpec projects are initialized with `npx tsp init` and compiled with `npx tsp compile`. The document also details generating Swagger examples, creating a Pull Request, and fixing CI check errors.\n\nExample usage of TypeSpec commands:\n```cli\nnpx tsp init https://aka.ms/typespec/azure-init\nnpx tsp compile .\n```\n\nAdditional code examples are available in the document, including generating Swagger examples with `oav generate-examples` and `oav run` commands.\n\nKEY TECHNICAL TERMS:\n\n1. TypeSpec\n2. Azure Rest API\n3. SDK development\n4. Node.js LTS\n5. npm ci\n6. TypeSpec VisualStudio extensions\n7. Dev Containers\n8. Github Codespaces\n9. OpenAPI\n10. Autorest \n\nLet me know if I can help with anything else.\n\n\n- [typespec-structure-guidelines.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/typespec-structure-guidelines.md): Guidelines for TypeSpec Project Repositories\nThis document provides guidelines for managing TypeSpec projects for Azure, including the structure of TypeSpec project repositories, service folder structure, libraries for service groups, specification versioning, and utilizing feature branches. The TypeSpec project repositories are organized under the `specification` folder, with each child folder corresponding to a service specification for a specific Azure team. The service folder contains the complete TypeSpec library specification for a service, which may include custom linter rules, methods, etc. \n\nFor example, a service folder for a compute service might include multiple TypeSpec files, such as `Compute.Management`, `Compute.CloudService.Management`, and `Compute.Disk.Management`. \n\n```\n-> specification\n   -> compute\n      -> Compute.Management               (management SDK + service)\n      -> Compute.CloudService.Management  (service)\n      -> Compute.Disk.Management          (service)\n```\n\nThe document also explains how to utilize feature branches for comparing proposed changes directly against the main branch and how to publish specifications by merging Pull Requests.\n\nAdditional code examples include how to reference shared libraries and how to structure service group libraries.\n\nSome key concepts include:\n- TypeSpec project repositories\n- Service folder structure\n- Specification versioning\n- Feature branches\n- Publishing specifications\n\nThe document also provides information on organizing services in folders, utilizing feature branches, and publishing specifications.\n\nKEY TERMS:\n- TypeSpec\n- Azure\n- Service folder structure\n- Specification versioning\n- Feature branches\n- Service group libraries\n- tspconfig.yaml\n- TypeSpec packages\n- Versioning decorators\n- Service specifications\n- Shared libraries\n\n\n- [uniform-versioning.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/uniform-versioning.md): Uniform Versioning in Azure REST API Specifications\nUniform versioning in Azure REST API specifications ensures that a service, its operation endpoints, documentation, and SDKs version in lockstep. This means that when a new service API version is released, a new documentation reference and SDK package must also be released. The service version is represented by a pair of folders, including its lifecycle stage and date, such as `stable/2024-03-05`. Each service within a service group can version independently, but must follow uniform versioning rules. The API version date must be later than the previous date, and `stable` and `preview` API versions cannot have the same date.\n\nFor example, consider a service with the following directory structure:\n```markdown\nservice/\nstable/\n2024-03-05/\nservice.json\noperation1.json\noperation2.json\npreview/\n2024-05-15-preview/\nservice.json\noperation1.json\noperation3.json\n```\nIn this example, the service has two API versions: `2024-03-05` (stable) and `2024-05-15-preview` (preview).\n\nAdditional code examples can be found in the [directory structure article] and [AutoRest config `README.md` file].\n\nCODE EXAMPLES:\n```markdown\n// Example of a service with multiple API versions\nservice/\nstable/\n2024-03-05/\nservice.json\noperation1.json\noperation2.json\npreview/\n2024-05-15-preview/\nservice.json\noperation1.json\noperation3.json\n```\n\nKEY TECHNICAL TERMS:\n\n1. Uniform versioning\n2. Service group\n3. API version\n4. Lifecycle stage\n5. Common-types\n6. AutoRest configuration\n7. Directory structure\n8. API version lifecycle stage\n9. Service version\n10. OpenAPI specification\n\n\n- [x-ms-examples.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/x-ms-examples.md): x-ms-examples Extension for Swagger Specifications\nThe `x-ms-examples` extension is used in Swagger specifications to provide multiple examples of requests and responses for an operation. This extension is a dictionary of different variations of examples for a given operation, allowing service teams to showcase various scenarios, such as different parameters or responses. The examples are stored in separate JSON files, located in an adjacent folder called `examples`, to keep the Swagger specification clean and easy to manage. The extension is applied at the operation level and provides a holistic picture of the entire request/response. For instance, an example file might contain parameters and responses for a specific operation, such as creating a storage account.\n\nExample of `x-ms-examples` extension in Swagger spec:\n```json5\n\"x-ms-examples\": {\n  \"Create a storage account\": { \"$ref\": \"./examples/createStorageAccount.json\" },\n  \"Update a storage account\": { \"$ref\": \"./examples/updateStorageAccount.json\" }\n}\n```\nExample of an individual example file (`createStorageAccount.json`):\n```json5\n{\n  \"parameters\": {\n    \"subscriptionId\": \"34adfa4f-cedf-4dc0-ba29-b6d1a69ab345\",\n    \"resourceGroupName\": \"testrg123\",\n    \"storageAccountName\": \"testacc6141\",\n    ...\n  },\n  \"responses\": {\n    \"200\": {\n      \"headers\": { ... },\n      \"body\": { ... }\n    }\n  }\n}\n```\nAdditional examples include various request/response scenarios, such as GET requests with or without `$expand`.\n\nKEY TECHNICAL TERMS:\n\n1. Swagger specification\n2. x-ms-examples extension\n3. Operation Object\n4. JSON schema\n5. API endpoint\n6. Request/response examples\n7. Swagger spec\n8. Example files\n9. API documentation\n10. REST API documentation\n\n\n\n## api-scenario\n\n\n### how-to\n\n\n\n- [GenerateABasicApiScenario.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/GenerateABasicApiScenario.md): Generate a Basic API Scenario File from Swagger\nThis document provides a step-by-step guide on generating a basic API scenario file from Swagger. It requires the installation of `oav` and `docker` as prerequisites. The process involves compiling Swagger into `dependencies.json` with Restler and then using `oav` to generate the API scenario file. The generated file contains all operations in the Swagger file, ordered by dependencies, with minimum required parameters filled in. The document also offers an alternative approach using Swagger examples to generate the API scenario file. Additionally, it mentions running the API scenario file with `oav run`. \n\nExample commands:\n```bash\ndocker run --rm -v $(pwd)/specification:/swagger -w /swagger/.restler_output mcr.microsoft.com/restlerfuzzer/restler dotnet /RESTler/restler/Restler.dll compile --api_spec /swagger/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json\n```\n```bash\noav generate-api-scenario static --specs specification/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json --dependency specification/.restler_output/Compile/dependencies.json -o specification/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/scenarios\n```\n\nNote that there are additional code examples in the document, including an alternative command that uses Swagger examples.\n\nKEY TECHNICAL TERMS:\n- oav\n- Restler\n- Swagger\n- API scenario file\n- dependencies.json\n- docker\n- Restlerfuzzer\n- API specification\n- Swagger examples\n\n\n- [MakeTestProxyRecording.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/MakeTestProxyRecording.md): Using API Scenario Test and Test-Proxy for Traffic Recording\nThis document explains how to use API Scenario Test and test-proxy to make traffic recording. It assumes familiarity with API Scenario test and focuses on utilizing test-proxy for recording and playback capabilities. The process involves preparing an assets.json file, making recordings, pushing them to an external Git repository, and restoring or resetting recordings as needed. Key steps include starting test-proxy, running API Scenario tests, checking recordings, and pushing or restoring recordings using specific commands.\n\nTo make traffic recording, start by preparing an `assets.json` file under the `scenarios/` folder with content specifying the assets repository and tag prefix:\n\n```json\n{\n  \"AssetsRepo\": \"Azure/azure-sdk-assets\",\n  \"AssetsRepoPrefixPath\": \"\",\n  \"TagPrefix\": \"apitest/<ServiceName>/<package>\"\n}\n```\n\nThen, make a recording by starting test-proxy and running an API Scenario test:\n\n```bash\ntest-proxy start\noav run <your-scenario-file>.yaml -e <your-env>.json --testProxy http://localhost:5000 --testProxyAssets <your-assets-file>.json\n```\n\nAdditional examples include pushing recordings to a Git repository and restoring them.\n\nKEY TECHNICAL TERMS:\n1. API Scenario Test\n2. test-proxy\n3. assets.json\n4. traffic recording\n5. test-proxy start\n6. oav run\n7. test-proxy push\n8. test-proxy restore\n9. test-proxy reset\n10. Swagger consistency validation\n\n\n- [QuickStart.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/QuickStart.md): Quick Start with API Scenario Test using OAV\nThis document provides a step-by-step guide on using OAV (Open-Source API Validator) for API scenario testing. It starts by introducing OAV, a powerful tool for Swagger validation, API scenario testing, and example generation. The guide covers installing OAV, creating an AAD app, authoring API scenario files, and running tests. It also explains how to debug tests using Postman. The document provides YAML and JSON code examples for defining API scenarios and environment files.\n\n```yaml\n# Example API scenario file in YAML\nscope: ResourceGroup\nvariables:\n  configStoreName:\n    type: string\n    prefix: configstor\n\nscenarios:\n  - scenario: quickStart\n    description: Quick start with AppConfiguration ConfigurationStores\n    steps:\n      - step: Operations_CheckNameAvailability\n        exampleFile: ../examples/CheckNameAvailable.json\n```\n\n```json\n// Example env.json file\n{\n  \"subscriptionId\": \"<your subscription id>\",\n  \"location\": \"westcentralus\",\n  \"tenantId\": \"<AAD app tenantId>\",\n  \"client_id\": \"<your add client_id>\",\n  \"client_secret\": \"<your aad client_secret>\"\n}\n```\n\nAdditional code examples include API scenario files using operation-based steps and Postman collection files.\n\nKEY TECHNICAL TERMS:\n1. OAV (Open-Source API Validator)\n2. API Scenario Testing\n3. Swagger Validation\n4. AAD (Azure Active Directory) App\n5. Postman Collection\n6. API Scenario Definition\n7. Azure API Guidelines\n8. Traffic Schema Validation\n9. Azure Resource Manager (ARM)\n10. API Example Generation\n\n\n- [ResolveDependencies.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/how-to/ResolveDependencies.md): Resolve External Dependencies in API Scenarios\nThis document discusses how to resolve external dependencies in API scenarios, specifically in Azure API Scenarios. It introduces two key features: external operation references and ARM Template integration. External operation references allow calling cross-RP REST APIs before or between scenario steps. ARM Template integration enables creating external Azure resources and executing PowerShell or Azure CLI scripts. The document provides examples of creating a VM with API Scenarios, including using external operation references and ARM Templates.\n\nFor instance, to create a VM, you can use the following YAML configuration:\n\n```yaml\nprepareSteps:\n  - step: createVirtualNetwork\n    operationId: VirtualNetworks_CreateOrUpdate\n    readmeTag: ../../../../../../network/resource-manager/readme.md#package-2021-05\n    parameters:\n      virtualNetworkName: $(vmName)-VNET\n      parameters:\n        location: $(location)\n        properties:\n          addressSpace:\n            addressPrefixes:\n              - 10.0.0.0/16\n          subnets:\n            - name: $(vmName)-Subnet\n              properties:\n                addressPrefix: 10.0.0.0/24\n    outputVariables:\n      subnetId:\n        type: string\n        fromResponse: /properties/subnets/0/id\n```\n\nAnd here's an example of using ARM Template to provision resources:\n\n```json\n{\n  \"$schema\": \"https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#\",\n  \"contentVersion\": \"1.0.0.0\",\n  \"parameters\": {\n    \"vmName\": {\n      \"type\": \"string\",\n      \"defaultValue\": \"test\"\n    }\n  },\n  \"variables\": {\n    \"VNETName\": \"[concat(parameters('vmName'), '-VNET')]\",\n    \"SubnetName\": \"[concat(parameters('vmName'), '-Subnet')]\",\n    \"NSGName\": \"[concat(parameters('vmName'), '-NSG')]\",\n    \"PublicIPName\": \"[concat(parameters('vmName'), '-PublicIP')]\",\n    \"VMNicName\": \"[concat(parameters('vmName'), '-VMNic')]\"\n  },\n  \"resources\": [\n    {\n      \"name\": \"[variables('VNETName')]\",\n      \"type\": \"Microsoft.Network/virtualNetworks\",\n      \"location\": \"[resourceGroup().location]\",\n      \"apiVersion\": \"2015-06-15\",\n      \"dependsOn\": [],\n      \"tags\": {},\n      \"properties\": {\n        \"addressSpace\": {\n          \"addressPrefixes\": [\n            \"10.0.0.0/16\"\n          ]\n        },\n        \"subnets\": [\n          {\n            \"name\": \"[variables('SubnetName')]\",\n            \"properties\": {\n              \"addressPrefix\": \"10.0.0.0/24\"\n            }\n          }\n        ]\n      }\n    }\n  ]\n}\n```\n\nAdditional code examples include using Azure PowerShell or CLI scripts with ARM Template deployment scripts.\n\nKey technical terms and topics:\n\n1. API Scenarios\n2. External operation references\n3. ARM Template integration\n4. Azure PowerShell\n5. Azure CLI\n6. Cross-RP resources\n7. REST API\n8. Azure resources\n9. ARM Template deployment scripts\n10. Network RP\n11. Compute RP\n\n\n\n### references\n\n\n\n- [ApiScenarioDefinition.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/ApiScenarioDefinition.md): API Scenario Definition Reference for Azure REST API\nThe API Scenario Definition Reference provides a comprehensive guide to creating and managing API scenarios, which are used to define a series of steps that can be executed against Azure resources. An API scenario is defined in a YAML file, which includes a scope, variables, and a list of scenarios. Each scenario consists of a series of steps, which can be REST calls, ARM template deployments, or role assignments. The reference details the structure and fields of the API scenario definition file, including the scope, variables, scenarios, and steps. It also explains how to define REST call steps, ARM template steps, ARM deployment script steps, and role assignment steps.\n\nFor example, a simple API scenario definition file might look like this:\n\n```yaml\nscope: ResourceGroup\nvariables:\n  configStoreName:\n    type: string\n    prefix: configstor\n\nscenarios:\n  - scenario: quickStart\n    description: Quick start with AppConfiguration ConfigurationStores\n    steps:\n      - step: Operations_CheckNameAvailability\n        operationId: Operations_CheckNameAvailability\n        parameters:\n          checkNameAvailabilityParameters:\n            name: $(configStoreName)\n            type: Microsoft.AppConfiguration/configurationStores\n```\n\nThis example defines an API scenario with a scope of ResourceGroup, a variable `configStoreName`, and a single scenario `quickStart` with a step to check the name availability of a configuration store.\n\nThe document also provides details on the different types of steps that can be defined, including REST call steps, ARM template steps, ARM deployment script steps, and role assignment steps.\n\nSome key concepts include:\n\n*   **Scope**: The scope of the API scenario, which can be ResourceGroup, Subscription, Tenant, or None.\n*   **Variables**: Key-value pairs that can be used throughout the API scenario.\n*   **Scenarios**: A list of scenarios that define a series of steps to be executed.\n*   **Steps**: Individual steps within a scenario, which can be REST calls, ARM template deployments, or role assignments.\n\nKey technical terms and topics:\n\n1.  API Scenario\n2.  REST Call Step\n3.  ARM Template Step\n4.  ARM Deployment Script Step\n5.  Role Assignment Step\n6.  JsonPatchOp\n7.  JsonTestOp\n8.  Variables\n9.  Scope\n10. Azure REST API\n\nAdditional code examples are available in the document, covering topics such as defining variables, using JSON patch operations, and working with ARM templates. \n\nHere are some JsonPatchOp examples:\n\n```yaml\n- add: /properties/items\n  value: 1\n\n- remove: /properties/items/1\n\n- replace: /properties/location\n  value: \"eastus\"\n\n- copy: /properties/items2\n  from: /properties/items\n\n- move: /properties/items2\n  from: /properties/items\n```\n\n\n- [ErrorCodeReference.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/ErrorCodeReference.md): API Test Error Codes for Azure REST API\nThis document outlines error codes and examples for Azure REST API testing, focusing on ensuring consistency between service responses and provided examples. It details specific error types, such as INCORRECT_PROVISIONING_STATE, RESPONSE_MISSING_VALUE, RESPONSE_ADDITIONAL_VALUE, RESPONSE_INCONSISTENT_VALUE, and ROUNDTRIP_INCONSISTENT_PROPERTY. These errors help in identifying issues with API responses, including incorrect provisioning states, missing or additional values, inconsistent values, and property discrepancies between request and response. The document provides examples of these errors and their expected resolutions.\n\nExample of RESPONSE_MISSING_VALUE and RESPONSE_ADDITIONAL_VALUE:\n```diff\n{\n   \"properties\":{\n      \"targetType\":\"blobNfs\",\n      \"junctions\":[\n         {\n            \"namespacePath\":\"/blobnfs\"\n         }\n      ],\n      \"blobNfs\":{\n         \"target\":\"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/scgroup/providers/Microsoft.Storage/storageAccounts/blofnfs/blobServices/default/containers/blobnfs\",\n-         \"usageModel\":\"WRITE_WORKLOAD_15\"\n      }\n   }\n}\n```\n \nAdditional code examples are available for various error scenarios.\n\nKEY TECHNICAL TERMS:\n1. Provisioning State\n2. ARM RPC\n3. API Testing\n4. REST API\n5. Azure Resource Manager\n6. ProvisioningState\n7. API Responses\n8. Error Codes\n9. API Examples\n10. Azure SDK\n\n\n- [Runner.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/Runner.md): Azure API Scenario Runner Behavior and Implementation\nThis document explains the expected behavior of a runner that consumes API scenarios, including loading API scenario files via OAV, managing scopes, and executing steps defined in the scenario. The runner can load variables, manage resource groups, and run ARM template deployments. It must follow variable definitions, replace variables in parameters, and check response status codes and bodies. The document outlines the procedure for running API scenarios, including preparing steps, executing REST calls and ARM template deployments, and extracting output variables.\n\nThe runner can be implemented using the following code example:\n```typescript\n// Load the API scenario file\nconst scenarioDef = await loader.load(\n  \"Microsoft.ContainerService/stable/2020-12-01/scenarios/containerService.yaml\"\n);\n\n// Setup initial variable env\nconst env = new VariableEnv();\nenv.setBatch({\n  subscriptionId: \"__your_subs_id_\",\n  location: \"westus\",\n  SSH_PUBLIC_KEY: \"__public_key_ssh__\"\n});\n\n// Execute the API scenario\nconst runner = new ApiScenarioRunner({\n  jsonLoader: loader.jsonLoader,\n  env,\n  client: new ApiScenarioRestClient(getDefaultAzureCredential(), {})\n});\n\ntry {\n  for (const scenario of scenarioDef.scenarios) {\n    await runner.executeScenario(scenario);\n  }\n} catch (e) {\n  console.log(e.message, e.stack);\n} finally {\n  console.timeLog(\"TestLoad\");\n  await runner.cleanAllScope();\n}\n```\n\nAnother example of replacing variables in `parameters`:\n```typescript\n// Replace variables in parameters\nconst parameters = {\n  name: \"$(variableName)\",\n  location: \"$(location)\"\n};\n// Fill the request via parameter definition in swagger and parameter value in `parameters`.\n```\n\nNote that there are more code examples in the document that demonstrate how to manage resource groups, run ARM template deployments, and extract output variables.\n\nKEY TECHNICAL TERMS:\n\n1. API Scenario\n2. OAV (OpenAPI Validator)\n3. ARM Template Deployment\n4. Variable Environment\n5. Resource Group\n6. REST Call\n7. Long Running Request\n8. API Scenario Loader\n9. ApiScenarioRunner\n10. Swagger File Paths\n\n\n- [Variables.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/api-scenario/references/Variables.md): Variables in API Scenarios\nThis document explains the concept of variables in API scenarios, including their types, definition levels, and usage. Variables can be defined at different levels: runtime, global, scope, scenario, and step. They can be referenced using the syntax `$(variableName)` and can be replaced recursively. The document also describes conventions for parameter names in examples, location, and Arm Template deployments. For instance, in a step with a request parameter `param`, its value will be replaced with `$(param)` to reference the variable value. Similarly, a top-level `location` property will be replaced with the variable value if it exists.\n\nExample:\n```yaml\nvariables:\n  resourceName: level-1\n\nscenarios:\n  - description: Create some resource\n    variables:\n      resourceName: level-2\n    steps:\n      - step: Create resource\n        variables:\n          resourceName: level-3\n        exampleFile: ../examples/ResourceCreate.json\n```\n\n```json\n{\n  \"parameters\": {\n    \"userName\": {\n      \"type\": \"string\"\n    }\n  },\n  \"resources\": [],\n  \"outputs\": {\n    \"nameResult\": {\n      \"type\": \"string\",\n      \"value\": \"[concat('prefix/', parameters['userName'])]\"\n    }\n  }\n}\n```\n\nNote that there are additional examples in the document, including API scenario and Arm Template deployment examples.\n\nKEY TERMS:\n1. Variables\n2. API scenario\n3. Arm Template\n4. Runtime variables\n5. SecureString\n6. Recursive replacement\n7. Parameter naming convention\n8. Location convention\n9. Arm Template Deployment\n10. Variable types\n\n\n\n## code-gen\n\n\n\n- [configure-cli.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-cli.md): Azure CLI Readme Configuration Guide\nThis document provides a comprehensive guide on configuring readme files for Azure CLI code generation. It explains the common configuration, tag settings, and Swagger to SDK configurations. The guide covers various aspects, including basic information, tag configurations, Swagger to SDK settings, and Az dedicated configurations. It also provides examples of how to configure readme files for different scenarios, such as multi-api and multi-packages.\n\nTo generate Azure CLI code, you need to configure readme.az.md, readme.cli.md, and readme.python.md files. The readme.cli.md file contains common configurations for all command line tools, while readme.az.md is specific to Azure CLI. The readme.python.md file is required for Azure CLI, which calls Azure SDK for Python under the implementation layer.\n\nThe configuration files use YAML syntax to define settings for different tags, input files, and output folders. For example, you can specify a tag and its corresponding input files:\n\n``` yaml\n$(tag) == 'package-2019-12-01'\ninput-file:\n- Microsoft.Compute/stable/2019-12-01/compute.json\n- Microsoft.Compute/stable/2019-12-01/runCommands.json\n- Microsoft.Compute/stable/2019-12-01/gallery.json\n```\n\nYou can also configure Swagger to SDK settings:\n\n``` yaml\n$(swagger-to-sdk)\nswagger-to-sdk:\n  - repo: azure-cli-extensions\n  - ...\n```\n\nThe Az dedicated configurations are defined in readme.az.md, which includes settings for Azure CLI extensions and main modules:\n\n``` yaml\n$(az) && $(target-mode) != 'core'\naz:\n    extensions: communication\n    namespace: azure.mgmt.communication\n    package-name: azure-mgmt-communication\naz-output-folder: $(azure-cli-extension-folder)/src/communication\npython-sdk-output-folder: \"$(az-output-folder)/azext_communication/vendored_sdks/communication\"\n```\n\nKey topics and technical terms:\n\n*   readme.az.md\n*   readme.cli.md\n*   readme.python.md\n*   Azure CLI\n*   Swagger to SDK\n*   Az configurations\n*   Multi-api\n*   Multi-packages\n*   Autorest\n\nThe document also mentions that for advance usage of CLI Codegen, one can refer to [autorest.az doc](https://github.com/Azure/autorest.az/tree/master/doc). \n\nAdditional code examples are available in the document, covering various scenarios and configurations. \n\nExamples of commands to run autorest for code generation:\n\n```bash\nautorest --az --use=@autorest/az@latest /home/qiaozha/code/azure-rest-api-specs/specification/storage/resource-manager/readme.md --azure-cli-extension-folder=../azure-cli-extensions\n```\n\n\n- [configure-go-sdk.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-go-sdk.md): Readme Configuration Guide for Azure SDK for Go\nThis document provides a comprehensive guide on configuring readme files for Azure SDK for Go code generation. It covers basic information configuration, tag definitions, Swagger to SDK settings, and Go-specific configurations. The guide explains how to generate and test Go SDKs using the configured readme files. It also includes code examples for generating Go SDKs and testing them locally.\n\nThe document outlines the necessary configurations for generating Go SDKs, including setting the package title, description, and tags. It also explains how to configure Swagger files for specific clients and generate SDKs using the `autorest` command. Additionally, it provides steps for testing generated Go SDKs locally.\n\nExample configurations for readme files:\n```yml\ntitle: xxxxConfigurationClient\ndescription: xxxx Configuration Client\nopenapi-type: arm\ntag: package-xxxx-xx-xx\n```\n\n```yml\n## Go\n\nThese settings apply only when `--go` is specified on the command line.\n\n```yaml $(go) && $(track2)\nlicense-header: MICROSOFT_MIT_NO_VERSION\nmodule-name: sdk/resourcemanager/agrifood/armagrifood\nmodule: github.com/Azure/azure-sdk-for-go/$(module-name)\noutput-folder: $(go-sdk-folder)/$(module-name)\nazure-arm: true\nmodule-version: 0.1.0\n```\nExtra code examples include configurations for Swagger to SDK and testing generated Go SDKs locally.\n\nKEY TECHNICAL TERMS:\n\n* Azure SDK for Go\n* Readme configuration\n* Swagger to SDK\n* Go SDK generation\n* Autorest command\n* Module name configuration\n* Output folder configuration\n* Azure arm configuration\n* Module version configuration\n\n\n- [configure-python-sdk.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-python-sdk.md): Readme Configuration Guide for Python SDK\nThis document provides a configuration guide for generating Python SDKs using Azure REST API specifications. It explains how to configure readme files to make them available for Python SDK code generation. The guide covers basic information configuration, tag definitions, and Swagger to SDK settings. It also provides examples of how to configure multi-API support, batch processing, and output folders for generated SDKs.\n\nThe document outlines the structure and syntax for readme files, including how to specify package information, tags, and input files for Swagger code generation. It also describes how to configure settings for Python SDK generation, such as namespace, output folder, and package version.\n\nFor example, to configure basic package information, you can use the following YAML code:\n``` yaml\ntitle: AppconfigurationConfigurationClient\ndescription: Appconfiguration Configuration Client\nopenapi-type: arm\ntag: package-2019-10-01\n```\nAdditionally, you can configure multi-API support using the `batch` section:\n``` yaml\nbatch:\n  - tag: package-2020-06-01-only\n  - tag: package-2020-05-01-only\n  - multiapiscript: true\n```\nThis document provides detailed information on configuring readme files for Python SDK generation, including code examples and technical terms.\n\nCODE EXAMPLES: \n- Basic Information Configuration: \n``` yaml\ntitle: AppconfigurationConfigurationClient\ndescription: Appconfiguration Configuration Client\nopenapi-type: arm\ntag: package-2019-10-01\n```\n- Multi-API Support Configuration:\n``` yaml\nbatch:\n  - tag: package-2020-06-01-only\n  - tag: package-2020-05-01-only\n  - multiapiscript: true\n```\n\nKEY TECHNICAL TERMS:\n\n* Azure REST API\n* Python SDK\n* Swagger\n* Autorest\n* Multi-API support\n* Batch processing\n* Code generation\n* OpenAPI\n* API versions\n\n\n- [configure-typescript-sdk.md](https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/code-gen/configure-typescript-sdk.md): Readme Configuration Guide for Azure SDK for Javascript (Typescript)\nThis document provides a configuration guide for Azure SDK for Javascript (Typescript) code generation. It explains how to configure readme files to make them available for the Azure SDK. The guide covers basic information configuration, tag configuration, swagger to SDK configuration, and Typescript configuration. It also provides examples of how to configure multiple packages and tags.\n\nTo configure the readme file, start by specifying basic package information such as title, description, and tag. For example:\n``` yaml\ntitle: xxxxConfigurationClient\ndescription: xxxx Configuration Client\nopenapi-type: arm\ntag: package-xxxx-xx-xx\n```\nThen, configure the tag by specifying the input files for a specific tag. For instance:\n``` yaml\n$(tag) == 'package-2019-12-01'\ninput-file:\n- Microsoft.Compute/stable/2019-12-01/compute.json\n- Microsoft.Compute/stable/2019-12-01/runCommands.json\n- Microsoft.Compute/stable/2019-12-01/gallery.json\n```\nThe document also provides an example of Typescript configuration:\n```yaml\ntypescript:\n  azure-arm: true\n  package-name: \"@azure/arm-apimanagement\"\n  output-folder: \"$(typescript-sdks-folder)/sdk/apimanagement/arm-apimanagement\"\n  clear-output-folder: true\n  generate-metadata: true\n```\nThis guide also mentions that Azure SDK for Javascript (Typescript) doesn't support multi-api and only supports single api packages.\n\nSome additional code examples are available in the document, including configurations for multi-packages and different tags.\n\nHere are some code examples:\n``` yaml\n$(swagger-to-sdk)\nswagger-to-sdk:\n  - repo: azure-sdk-for-js\n  - ...\n```\n```yaml\n$(typescript) && !$(profile)\ntypescript:\n  package-name: \"@azure/arm-features\"\n  output-folder: \"$(typescript-sdks-folder)/sdk/features/arm-features\"\n  clear-output-folder: true\n```\n\nKEY TECHNICAL TERMS:\n\n* Azure SDK for Javascript (Typescript)\n* Swagger to SDK\n* Typescript Configuration\n* Multi-api\n* Multi-packages\n* Autorest\n* azure-sdk-for-js\n* Typescript-sdks-folder\n* openapi-type\n* Tag configuration\n\n\n\n## onboard-dpg-in-sdkautomation\n\n\n\n- [Integrate-dpg-and-apiview-in-sdk-automation-pipeline.md](https://raw.githubusercontent.com/Azu