Skip to content

Commit f68e478

Browse files
tadeleshtadelesh
authored
Update go SDK config doc (#19526)
* update go sdk config doc * change to go-sdk-folder
1 parent faf8c2c commit f68e478

File tree

1 file changed

+11
-194
lines changed

1 file changed

+11
-194
lines changed

‎documentation/code-gen/configure-go-sdk.md

Lines changed: 11 additions & 194 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ tag: package-xxxx-xx-xx
2020
```
2121
~~~~
2222

23-
### tag
23+
### Tag
2424

2525
Tags are used to define what swagger files are used in specific client SDK. In Single-API client, only one tag can be used to generate SDK client.
2626
A tag can contains a bunch of swagger files which are used to generate the SDK.
@@ -79,10 +79,8 @@ See configuration in [readme.go.md](./readme.go.md)
7979

8080
Go dedicated configurations are configured in `readme.go.md`.
8181

82-
The typical namespace/package-name in azure-sdk-for-go must start with a lower case letter and can only contain lower case letters and numbers.
83-
And the typical output-folder in the azure-sdk-for-go is like `$(typescript-sdk-folder)/services/$(namespace)/mgmt/yyyy-mm-dd/$(namespace)` where the `yyyy-mm-dd` is the version of this package.
84-
85-
Go SDK supports multi-api by default, therefore you must add a batch section in the `readme.go.md`.
82+
The typical module name in azure-sdk-for-go has prefix `sdk/`. Data plane packages always use pattern `sdk/$(rp)/az$(namespace)` as module name while management packages use pattern `sdk/resourcemanager/$(rp)/arm$(namespace)`.
83+
Full module path in azure-sdk-for-go is like `github.com/Azure/azure-sdk-for-go/$(module-name)` and the typical output-folder in the azure-sdk-for-go is like `$(go-sdk-folder)/$(module-name)`.
8684

8785
A typical readme.go.md is like this:
8886
~~~
@@ -92,200 +90,19 @@ A typical readme.go.md is like this:
9290
9391
These settings apply only when `--go` is specified on the command line.
9492
95-
```yaml $(go)
96-
go:
97-
license-header: MICROSOFT_APACHE_NO_VERSION
98-
clear-output-folder: true
99-
```
100-
101-
### Go multi-api
102-
103-
``` yaml $(go) && $(multiapi)
104-
batch:
105-
- tag: package-2019-12-01
106-
```
107-
108-
### Tag: package-2019-12-01 and go
109-
110-
These settings apply only when `--tag=package-2019-12-01 --go` is specified on the command line.
111-
Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
112-
113-
```yaml $(tag) == 'package-2019-12-01' && $(go)
114-
namespace: yourservicename
115-
output-folder: $(go-sdk-folder)/services/$(namespace)/mgmt/2019-12-01/$(namespace)
116-
```
117-
~~~
118-
119-
## Preview package and stable package
120-
121-
Preview tags and stable tags are defined as the following:
122-
123-
- A tag is a preview tag when there is at least one input swagger file is preview.
124-
- A tag is a stable tag when all of its swagger files are stable.
125-
126-
A stable tag generates a stable package in `azure-sdk-for-go`, and its `output-folder` must be in this pattern:
127-
```
128-
output-folder: $(go-sdk-folder)/services/$(namespace)/mgmt/yyyy-mm-dd/$(namespace)
129-
```
130-
The `output-folder` here must not be under the `preview` subdirectory.
131-
132-
A preview tag generates a preview package in `azure-sdk-for-go`, and its `output-folder` must be in this pattern:
133-
```
134-
output-folder: $(go-sdk-folder)/services/preview/$(namespace)/mgmt/yyyy-mm-dd-preview/$(namespace)
135-
```
136-
The `output-folder` here must be under the `preview` subdirectory.
137-
138-
These rules must be applied, otherwise the go code generator will throw exceptions.
139-
140-
## Multi-packages
141-
142-
The batch is a tag list which are used in the one RP has multi-package scenarios. For example,
143-
the Resources RP has several independent packages like features, lock, policy.
144-
First of all, you need to have different yaml block for each package to define the default tag for that specific package.
145-
~~~
146-
// file: readme.md
147-
## Configuration
148-
149-
### Basic Information
150-
151-
These are the global settings for the Resource API.
152-
153-
``` yaml
154-
openapi-type: arm
155-
```
156-
157-
``` yaml $(package-features)
158-
tag: package-features-2015-12
93+
```yaml $(go) && $(track2)
94+
license-header: MICROSOFT_MIT_NO_VERSION
95+
module-name: sdk/resourcemanager/agrifood/armagrifood
96+
module: github.com/Azure/azure-sdk-for-go/$(module-name)
97+
output-folder: $(go-sdk-folder)/$(module-name)
98+
azure-arm: true
99+
module-version: 0.1.0
159100
```
160-
161-
``` yaml $(package-locks)
162-
tag: package-locks-2016-09
163-
```
164-
165-
``` yaml $(package-policy)
166-
tag: package-policy-2019-09
167-
```
168-
169-
``` yaml $(package-resources)
170-
tag: package-resources-2020-06
171-
```
172-
173-
~~~
174-
Then for each default tag, you can define the input swagger like normal tag.
175101
~~~
176102

177-
### Tag: package-features-2015-12
178-
179-
These settings apply only when `--tag=package-features-2015-12` is specified on the command line.
180-
181-
``` yaml $(tag) == 'package-features-2015-12'
182-
input-file:
183-
- Microsoft.Features/stable/2015-12-01/features.json
184-
```
185-
186-
### Tag: package-locks-2016-09-preview
187-
188-
These settings apply only when `--tag=package-locks-2016-09-preview` is specified on the command line.
189-
190-
``` yaml $(tag) == 'package-locks-2016-09-preview'
191-
input-file:
192-
- Microsoft.Authorization/preview/2016-09-01/locks.json
193-
```
194-
195-
### Tag: package-policy-2019-09
196-
197-
These settings apply only when `--tag=package-policy-2019-09` is specified on the command line.
198-
199-
``` yaml $(tag) == 'package-policy-2019-09'
200-
input-file:
201-
- Microsoft.Authorization/stable/2019-09-01/policyAssignments.json
202-
- Microsoft.Authorization/stable/2019-09-01/policyDefinitions.json
203-
- Microsoft.Authorization/stable/2019-09-01/policySetDefinitions.json
204-
205-
# Needed when there is more than one input file
206-
override-info:
207-
title: PolicyClient
208-
```
209-
210-
### Tag: package-resources-2020-06
211-
212-
These settings apply only when `--tag=package-resources-2020-06` is specified on the command line.
213-
214-
``` yaml $(tag) == 'package-resources-2020-06'
215-
input-file:
216-
- Microsoft.Resources/stable/2020-06-01/resources.json
217-
```
218-
~~~
219-
220-
Finally, in your readme.go.md you should include what packages you want to include in the Azure SDK for Go.
221-
And in each package's section define the default package name output folder in azure-sdk-for-go repo etc.
222-
223-
~~~
224-
## Go
225-
226-
These settings apply only when `--go` is specified on the command line.
227-
228-
```yaml $(go)
229-
go:
230-
license-header: MICROSOFT_APACHE_NO_VERSION
231-
clear-output-folder: true
232-
```
233-
234-
### Go multi-api
235-
236-
``` yaml $(go) && $(multiapi)
237-
batch:
238-
- tag: package-features-2015-12
239-
- tag: package-locks-2016-09-preview
240-
- tag: package-policy-2019-09
241-
- tag: package-resources-2020-06
242-
```
243-
244-
### Tag: package-features-2015-12 and go
245-
246-
These settings apply only when `--tag=package-features-2015-12 --go` is specified on the command line.
247-
Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
248-
249-
```yaml $(tag) == 'package-features-2015-12' && $(go)
250-
namespace: features
251-
output-folder: $(go-sdk-folder)/services/resources/mgmt/2015-12-01-preview/$(namespace)
252-
```
253-
254-
### Tag: package-locks-2016-09-preview and go
255-
256-
These settings apply only when `--tag=package-locks-2016-09-preview --go` is specified on the command line.
257-
Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
258-
259-
```yaml $(tag) == 'package-locks-2016-09-preview' && $(go)
260-
namespace: locks
261-
output-folder: $(go-sdk-folder)/services/preview/resources/mgmt/2016-09-01-preview/$(namespace)
262-
```
263-
264-
### Tag: package-policy-2019-09 and go
265-
266-
These settings apply only when `--tag=package-policy-2019-09 --go` is specified on the command line.
267-
Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
268-
269-
```yaml $(tag) == 'package-policy-2019-09' && $(go)
270-
namespace: policy
271-
output-folder: $(go-sdk-folder)/services/resources/mgmt/2019-09-01/$(namespace)
272-
```
273-
274-
### Tag: package-resources-2020-06 and go
275-
276-
These settings apply only when `--tag=package-resources-2020-06 --go` is specified on the command line.
277-
Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
278-
279-
```yaml $(tag) == 'package-resources-2020-06' && $(go)
280-
namespace: resources
281-
output-folder: $(go-sdk-folder)/services/resources/mgmt/2020-06-01/$(namespace)
282-
```
283-
~~~
284-
285-
286103
## Run codegen
287104

288105
After configure all the readme files, autorest can be used to generate SDK.
289106
~~~
290-
autorest --go --use="@microsoft.azure/autorest.go@~2.1.156" --multiapi --preview-chk --use-onever --go-sdk-folder=/path/to/azure-sdk-for-go /path/to/azure-rest-api-specs/specification/storage/resource-manager/readme.md
107+
autorest --go --use=@autorest/go@latest --go --track2 --go-sdk-folder=/path/to/azure-sdk-for-go /path/to/azure-rest-api-specs/specification/agrifood/resource-manager/readme.md
291108
~~~

0 commit comments

Comments
 (0)