Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refactor sql readme.md #2640

Merged
merged 5 commits into from
Mar 14, 2018
Merged

Refactor sql readme.md #2640

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9c705de
Refactor sql readme.md
jaredmoo Mar 13, 2018
1711aae
Added package-pure-2017-10 including Go support
jaredmoo Mar 13, 2018
f7be3a9
Commented on Go api-versions
jaredmoo Mar 13, 2018
7c0740c
Removed bad python section
jaredmoo Mar 13, 2018
274ea7f
Fixed typo in 2017-10 go package
jaredmoo Mar 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 86 additions & 57 deletions specification/sql/resource-manager/readme.md
View file
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this makes a lot of sense. It makes explicit the composite nature of input-file tags.

To be clear though, the v1 here isn't something that we expect to be exposed to customers, and is just a hint for the SDK creator, right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct

```

## 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I love that tag :)


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-103-01-preview/sql
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo here! Looks like the date is malformed.

```

#### 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove this Python section, there is currently two Python sections in this file and this one is the bad one.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, thx


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