Skip to content

Commit

Permalink
Refactor sql readme.md (#2640)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@jaredmoo @marstr
jaredmoo authored and marstr committed Mar 14, 2018
1 parent f010d06 commit 71b71ff
Showing 1 changed file with 86 additions and 57 deletions.
143 changes: 86 additions & 57 deletions specification/sql/resource-manager/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,42 +4,42 @@
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`
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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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=<path to "SDKs" directory of your azure-sdk-for-net clone>`.
Expand All @@ -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=<path to the root directory of your azure-sdk-for-python clone>`.
Expand All @@ -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.

Expand All @@ -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=<path to the root directory of your azure-sdk-for-go clone>`.

``` 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=<path to the root directory of your azure-sdk-for-go clone>`.
Expand All @@ -387,7 +431,7 @@ Please also specify `--go-sdk-folder=<path to the root directory of your azure-s
output-folder: $(go-sdk-folder)/services/sql/mgmt/2017-03-01-preview/sql
```

### Tag: package-2015-05-preview and go
#### Tag: package-2015-05-preview and go

These settings apply only when `--tag=package-2015-05-preview --go` is specified on the command line.
Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
Expand All @@ -396,7 +440,7 @@ Please also specify `--go-sdk-folder=<path to the root directory of your azure-s
output-folder: $(go-sdk-folder)/services/sql/mgmt/2015-05-01-preview/sql
```

### Tag: package-2014-04 and go
#### Tag: package-2014-04 and go

These settings apply only when `--tag=package-2014-04 --go` is specified on the command line.
Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
Expand All @@ -405,22 +449,7 @@ Please also specify `--go-sdk-folder=<path to the root directory of your azure-s
output-folder: $(go-sdk-folder)/services/sql/mgmt/2014-04-01/sql
```


## Python

These settings apply only when `--python` is specified on the command line.

``` yaml $(python)
python:
# override the default output folder
output-folder: $(output-folder)/python
license-header: MICROSOFT_MIT_NO_VERSION
payload-flattening-threshold: 2
namespace: azure.mgmt.sql
```


## Java
### Java

These settings apply only when `--java` is specified on the command line.
Please also specify `--azure-libraries-for-java-folder=<path to the root directory of your azure-libraries-for-java clone>`.
Expand All @@ -435,7 +464,7 @@ java:
output-folder: $(azure-libraries-for-java-folder)/azure-mgmt-sql
```

# Validation
## Validation

``` yaml
directive:
Expand Down

0 comments on commit 71b71ff

Please sign in to comment.