From 71b71ffd57e4faf0f0a429dc4f6f6695cc976e1f Mon Sep 17 00:00:00 2001 From: Jared Moore Date: Wed, 14 Mar 2018 15:12:54 -0700 Subject: [PATCH] Refactor sql readme.md (#2640) * Refactor sql readme.md - Rename schema-* to package-pure-* in order to follow convention for python multi-version - Rename package-2017-10-preview to package-composite-v1. The reasons for this are explained in package-2017-03-01-preview tag. The next tag that I add in the near future will be package-composite-v2, which will represent a breaking change & major version bump for clients. - Improved description of various sections - Whitespace/header consistency * Added package-pure-2017-10 including Go support * Commented on Go api-versions * Removed bad python section * Fixed typo in 2017-10 go package --- specification/sql/resource-manager/readme.md | 143 +++++++++++-------- 1 file changed, 86 insertions(+), 57 deletions(-) diff --git a/specification/sql/resource-manager/readme.md b/specification/sql/resource-manager/readme.md index 5fec64a5f7b8..1292c7108f8b 100644 --- a/specification/sql/resource-manager/readme.md +++ b/specification/sql/resource-manager/readme.md @@ -4,10 +4,8 @@ This is the AutoRest configuration file for Sql. - - ---- ## Getting Started + To build the SDK for Sql, simply [Install AutoRest](https://aka.ms/autorest/install) and in this folder, run: > `autorest` @@ -15,31 +13,33 @@ To build the SDK for Sql, simply [Install AutoRest](https://aka.ms/autorest/inst To see additional help and options, run: > `autorest --help` ---- ## Configuration - - ### Basic Information + These are the global settings for the Sql API. ``` yaml title: SqlManagementClient description: The Azure SQL Database management API provides a RESTful set of web services that interact with Azure SQL Database services to manage your databases. The API enables you to create, retrieve, update, and delete databases. openapi-type: arm -tag: package-2017-03-preview +tag: package-composite-v1 ``` -## Configuration for generating client SDKs +## Composite packages + +The following packages may be composed from multiple api-versions. -### Tag: package-2017-10-preview +### Tag: package-composite-v1 -These settings apply only when `--tag=package-2017-10-preview` is specified on the command line. +These settings apply only when `--tag=package-composite-v1` is specified on the command line. -This section contains the input swagger files that are used when generating client SDKs up to and including api-version 2017-10-01-preview. APIs should only be added to this section when the API is ready for production and the generated client code has been tested end-to-end. +This section contains the "composite-v1" set of APIs, which is composed from a selection of api-versions that will remain backwards compatible with "v1" clients such as .NET SDK Microsoft.Azure.Management.Sql version 1.x. -``` yaml $(tag) == 'package-2017-10-preview' +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. + +``` yaml $(tag) == 'package-composite-v1' input-file: - Microsoft.Sql/stable/2014-04-01/backupLongTermRetentionPolicies.json - Microsoft.Sql/stable/2014-04-01/backupLongTermRetentionVaults.json @@ -89,7 +89,9 @@ override-info: These settings apply only when `--tag=package-2017-03-preview` is specified on the command line. -This section contains the input swagger files that are used when generating client SDKs up to and including api-version 2017-03-01-preview. APIs should only be added to this section when the API is ready for production and the generated client code has been tested end-to-end. +This section contains the input swagger files that are used when generating client SDKs up to and including api-version 2017-03-01-preview, except databases.json which remains at api-version 2014-04-01 in order to maintain compatibility with clients that have been previously released with this package. To prevent similar confusion moving forward, sections named like `package-20xx-xx(-preview)` will not be used after package-2017-03-preview. Instead, sections named like `package-composite-vx` will be used to compose across api-versions and `package-pure-20xx-xx(-preview)` will be used for single api-versions. + +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. ``` yaml $(tag) == 'package-2017-03-preview' input-file: @@ -141,7 +143,9 @@ override-info: These settings apply only when `--tag=package-2015-05-preview` is specified on the command line. -This section contains the input swagger files that are used when generating client SDKs up to and including api-version 2015-05-01-preview. APIs should only be added to this section when the API is ready for production and the generated client code has been tested end-to-end. +This section contains the input swagger files that are used when generating client SDKs up to and including api-version 2015-05-01-preview. + +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. ``` yaml $(tag) == 'package-2015-05-preview' input-file: @@ -187,6 +191,8 @@ override-info: These settings apply only when `--tag=package-2014-04` is specified on the command line. +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. + ``` yaml $(tag) == 'package-2014-04' input-file: - Microsoft.Sql/stable/2014-04-01/checkNameAvailability.json @@ -203,17 +209,41 @@ override-info: title: SqlManagementClient ``` -## Configuration for generating resource manager schemas +## Pure package versions + +The following packages are each composed of all apis from only one api-version. + +### Tag: package-pure-2017-10-preview + +These settings apply only when `--tag=package-pure-2017-10-preview` is specified on the command line. + +This section contains all input swagger files for version 2017-10-01-preview. All APIs of that version must be added this section when the API is ready for production. + +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. + +These can be regenerated by running the following PowerShell script from this readme file's folder: `dir .\Microsoft.Sql\2017-03-01-preview\ -File | Resolve-Path -Relative | % { " - $_".Replace("\", "/") }` + +``` yaml $(tag) == 'package-pure-2017-10-preview' +input-file: + - ./Microsoft.Sql/preview/2017-10-01-preview/cancelOperations.json + - ./Microsoft.Sql/preview/2017-10-01-preview/cancelPoolOperations.json + +# Needed when there is more than one input file +override-info: + title: SqlManagementClient +``` + +### Tag: package-pure-2017-03-preview -### Tag: schema-2017-03-preview +These settings apply only when `--tag=package-pure-2017-03-preview` is specified on the command line. -These settings apply only when `--tag=schema-2017-03-preview` is specified on the command line. +This section contains all input swagger files for version 2017-03-01-preview. All APIs of that version must be added this section when the API is ready for production. -This section contains the input swagger files that are used when generating resource manager schemas for version 2017-03-01-preview. All APIs of that version must be added this section when the API is ready for production. +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. These can be regenerated by running the following PowerShell script from this readme file's folder: `dir .\Microsoft.Sql\2017-03-01-preview\ -File | Resolve-Path -Relative | % { " - $_".Replace("\", "/") }` -``` yaml $(tag) == 'schema-2017-03-preview' +``` yaml $(tag) == 'package-pure-2017-03-preview' input-file: - ./Microsoft.Sql/preview/2017-03-01-preview/databases.json - ./Microsoft.Sql/preview/2017-03-01-preview/renameDatabase.json @@ -225,15 +255,17 @@ override-info: title: SqlManagementClient ``` -### Tag: schema-2015-05-preview +### Tag: package-pure-2015-05-preview + +These settings apply only when `--tag=package-pure-2015-05-preview` is specified on the command line. -These settings apply only when `--tag=schema-2015-05-preview` is specified on the command line. +This section contains all input swagger files for version 2015-05-01-preview. All APIs of that version must be added this section when the API is ready for production. -This section contains the input swagger files that are used when generating resource manager schemas for version 2015-05-01-preview. All APIs of that version must be added this section when the API is ready for production. +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. These can be regenerated by running the following PowerShell script from this readme file's folder: `dir .\Microsoft.Sql\2015-05-01-preview\ -File | Resolve-Path -Relative | % { " - $_".Replace("\", "/") }` -``` yaml $(tag) == 'schema-2015-05-preview' +``` yaml $(tag) == 'package-pure-2015-05-preview' input-file: - ./Microsoft.Sql/preview/2015-05-01-preview/advisors.json - ./Microsoft.Sql/preview/2015-05-01-preview/blobAuditingPolicies.json @@ -253,15 +285,17 @@ override-info: title: SqlManagementClient ``` -### Tag: schema-2014-04 +### Tag: package-pure-2014-04 -These settings apply only when `--tag=schema-2014-04` is specified on the command line. +These settings apply only when `--tag=package-pure-2014-04` is specified on the command line. -This section contains the input swagger files that are used when generating resource manager schemas for version 2014-04-01-preview. All APIs of that version must be added this section when the API is ready for production. +This section contains all input swagger files for version 2014-04-01-preview. All APIs of that version must be added this section when the API is ready for production. + +APIs must only be added to this section when the API is publicly available in at least 1 production region and at least 1 generated client has been tested end-to-end. These can be regenerated by running the following PowerShell script from this readme file's folder: `dir .\Microsoft.Sql\2014-04-01\ -File | Resolve-Path -Relative | % { " - $_".Replace("\", "/") }` -``` yaml $(tag) == 'schema-2014-04' +``` yaml $(tag) == 'package-pure-2014-04' input-file: - ./Microsoft.Sql/stable/2014-04-01/advisors.json - ./Microsoft.Sql/stable/2014-04-01/backupLongTermRetentionPolicies.json @@ -298,10 +332,9 @@ override-info: ``` --- -# Code Generation - +## Code Generation -## Swagger to SDK +### Swagger to SDK This section describes what SDK should be generated by the automatic system. This is not used by Autorest itself. @@ -313,8 +346,7 @@ swagger-to-sdk: - repo: azure-sdk-for-go ``` - -## C# +### C# These settings apply only when `--csharp` is specified on the command line. Please also specify `--csharp-sdks-folder=`. @@ -328,7 +360,7 @@ csharp: clear-output-folder: true ``` -## Python +### Python These settings apply only when `--python` is specified on the command line. Please also specify `--python-sdks-folder=`. @@ -345,20 +377,20 @@ python: package-version: 0.9.0 clear-output-folder: true ``` + ``` yaml $(python) && $(python-mode) == 'update' python: no-namespace-folders: true output-folder: $(python-sdks-folder)/azure-mgmt-sql/azure/mgmt/sql ``` + ``` yaml $(python) && $(python-mode) == 'create' python: basic-setup-py: true output-folder: $(python-sdks-folder)/azure-mgmt-sql ``` - - -## Go +### Go These settings apply only when `--go` is specified on the command line. @@ -369,16 +401,28 @@ go: clear-output-folder: true ``` -### Go multi-api +#### Go multi-api + +From api-version 2017-10 and onwards, only pure package versions should be used. Composite package versions are used for earlier api-versions (2017-03 and earlier) in order to ensure backwards compatibility with previously released versions of Go SDK, ``` yaml $(go) && $(multiapi) batch: + - tag: package-pure-2017-10-preview - tag: package-2017-03-preview - tag: package-2015-05-preview - tag: package-2014-04 ``` -### Tag: package-2017-03-preview and go +#### Tag: package-pure-2017-10-preview and go + +These settings apply only when `--tag=package-2017-10-preview --go` is specified on the command line. +Please also specify `--go-sdk-folder=`. + +``` yaml $(tag) == 'package-pure-2017-10-preview' && $(go) +output-folder: $(go-sdk-folder)/services/sql/mgmt/2017-10-01-preview/sql +``` + +#### Tag: package-2017-03-preview and go These settings apply only when `--tag=package-2017-03-preview --go` is specified on the command line. Please also specify `--go-sdk-folder=`. @@ -387,7 +431,7 @@ Please also specify `--go-sdk-folder=`. @@ -396,7 +440,7 @@ Please also specify `--go-sdk-folder=`. @@ -405,22 +449,7 @@ Please also specify `--go-sdk-folder=`. @@ -435,7 +464,7 @@ java: output-folder: $(azure-libraries-for-java-folder)/azure-mgmt-sql ``` -# Validation +## Validation ``` yaml directive: