Skip to content

Commit fdb47aa

Browse files
ldmingldming
committed
chore: improve readme (#40)
(cherry picked from commit 3c4cb5d)
1 parent 2db12d3 commit fdb47aa

File tree

6 files changed

+352
-50
lines changed

6 files changed

+352
-50
lines changed

‎.generator/src/generator/templates/configuration.j2‎

Lines changed: 12 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -155,28 +155,7 @@ func NewConfiguration() *Configuration {
155155
UserAgent: getUserAgent(),
156156
Debug: false,
157157
Compress: true,
158-
Servers: ServerConfigurations{
159-
{%- for server in openapi.servers %}
160-
{{ server_configuration(server)|indent("\t"*3) }},
161-
{%- endfor %}
162-
},
163-
OperationServers: map[string]ServerConfigurations{
164-
{%- for version, spec in all_specs.items() %}
165-
{%- for path in spec.paths.values() %}
166-
{%- for operation in path.values() %}
167-
{%- for server in operation.servers %}
168-
{%- if loop.first %}
169-
"{{ version }}.{{ operation.tags[0].replace(" ", "") }}Api.{{ operation.operationId }}": {
170-
{%- endif %}
171-
{{ server_configuration(server)|indent("\t"*4) }},
172-
{%- if loop.last %}
173-
},
174-
{%- endif %}
175-
{%- endfor %}
176-
{%- endfor %}
177-
{%- endfor %}
178-
{%- endfor %}
179-
},
158+
Servers: ServerConfigurations{},
180159
unstableOperations: map[string]bool{
181160
{%- for version, api in apis.items() %}
182161
{%- for operations in api.values() %}
@@ -189,7 +168,7 @@ func NewConfiguration() *Configuration {
189168
{%- endfor %}
190169
},
191170
RetryConfiguration: RetryConfiguration{
192-
EnableRetry: false,
171+
EnableRetry: true,
193172
BackOffMultiplier: 2,
194173
BackOffBase: 2,
195174
HTTPRetryTimeout: 60 * time.Second,
@@ -310,6 +289,16 @@ func (c *Configuration) ServerURLWithContext(ctx context.Context, endpoint strin
310289
return "", err
311290
}
312291

292+
if len(sc) == 0 {
293+
for k, v := range variables {
294+
sc = append(sc, ServerConfiguration{
295+
URL: v,
296+
Description: k,
297+
Variables: map[string]ServerVariable{},
298+
})
299+
}
300+
}
301+
313302
return sc.URL(index, variables)
314303
}
315304

‎README.md‎

Lines changed: 236 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,242 @@
11
# kb-cloud-client-go
2-
Golang client for the KubeBlocks Cloud API
32

3+
This repository contains a Go API client for the KubeBlocks Cloud API.
44

5-
## Generate API
5+
## Requirements
6+
7+
* Go 1.22+
8+
9+
## Installation
10+
11+
```bash
12+
go get github.com/apecloud/kb-cloud-client-go
13+
```
14+
15+
## Layout
16+
17+
The client library contains the following packages:
18+
19+
### The KubeBlocks Cloud API Client
20+
21+
The main API client is located in the `api/kbcloud` directory. Import it with:
22+
23+
```go
24+
import "github.com/apecloud/kb-cloud-client-go/api/kbcloud"
25+
```
26+
27+
### The Admin API Client
28+
29+
The admin API client is located in the `api/kbcloud/admin` directory. Import it with:
30+
31+
```go
32+
import "github.com/apecloud/kb-cloud-client-go/api/kbcloud/admin"
33+
```
34+
35+
## Authentication
36+
37+
The client supports authentication via API Key & Secret. The recommended way is to use environment variables with NewDefaultContext:
38+
39+
```go
40+
// Use environment variables:
41+
// KB_CLOUD_API_KEY_NAME - API key name
42+
// KB_CLOUD_API_KEY_SECRET - API key secret
43+
// KB_CLOUD_SITE - Optional site configuration
44+
ctx := common.NewDefaultContext(context.Background())
45+
```
46+
47+
You can also configure authentication directly through context:
48+
49+
### API Key & Secret via Context
50+
51+
```go
52+
ctx := context.WithValue(
53+
context.Background(),
54+
common.ContextDigestAuth,
55+
common.DigestAuth{
56+
UserName: os.Getenv("KB_CLOUD_API_KEY_NAME"),
57+
Password: os.Getenv("KB_CLOUD_API_KEY_SECRET"),
58+
},
59+
)
60+
```
61+
62+
## Getting Started
63+
64+
For complete examples, check out the [examples](./examples) directory.
65+
66+
Here's an example using API key authentication:
67+
68+
```go
69+
package main
70+
71+
import (
72+
"context"
73+
"fmt"
74+
"os"
75+
76+
"github.com/apecloud/kb-cloud-client-go/api/common"
77+
"github.com/apecloud/kb-cloud-client-go/api/kbcloud"
78+
)
79+
80+
func main() {
81+
// Set up authentication context
82+
ctx := context.WithValue(
83+
context.Background(),
84+
common.ContextDigestAuth,
85+
common.DigestAuth{
86+
UserName: os.Getenv("KB_CLOUD_API_KEY_NAME"),
87+
Password: os.Getenv("KB_CLOUD_API_KEY_SECRET"),
88+
},
89+
)
90+
91+
// Optional: Set site configuration
92+
ctx = context.WithValue(
93+
ctx,
94+
common.ContextServerVariables,
95+
map[string]string{"site": os.Getenv("KB_CLOUD_SITE")},
96+
)
97+
98+
orgName := "my-org"
99+
client := common.NewAPIClient(configuration)
100+
fmt.Println("Listing environments...")
101+
api := kbcloud.NewEnvironmentApi(client)
102+
envs, resp, err := api.ListEnvironment(ctx, orgName)
103+
if err != nil {
104+
log.Fatalf("Error listing environments: %v\nResponse: %v", err, resp)
105+
}
106+
fmt.Printf("Environments: %+v\n\n", envs)
107+
}
108+
```
109+
110+
### Configuration Options
111+
112+
#### Environment Variables
113+
114+
The client supports the following environment variables:
115+
116+
```bash
117+
# Authentication
118+
KB_CLOUD_API_KEY_NAME=your-api-key-name
119+
KB_CLOUD_API_KEY_SECRET=your-api-key-secret
120+
121+
# Site configuration
122+
KB_CLOUD_SITE=https://api-test.apecloud.com
123+
124+
# HTTP proxy settings
125+
HTTP_PROXY=http://proxy.example.com:8080
126+
HTTPS_PROXY=http://proxy.example.com:8080
127+
```
128+
129+
#### Server Configuration
130+
131+
Configure server URL and variables:
132+
133+
```go
134+
configuration := kbcloud.NewConfiguration()
135+
136+
// Set server URL
137+
configuration.Host = "api.example.com"
138+
139+
// Set server variables
140+
configuration.ServerVariables = map[string]string{
141+
"site": os.Getenv("KB_CLOUD_SITE"),
142+
}
143+
144+
// Or use context to set server variables
145+
ctx := context.WithValue(
146+
context.Background(),
147+
common.ContextServerVariables,
148+
map[string]string{"site": os.Getenv("KB_CLOUD_SITE")},
149+
)
150+
```
151+
152+
#### Debug Mode
153+
154+
Enable debug logging:
155+
156+
```go
157+
configuration := kbcloud.NewConfiguration()
158+
configuration.Debug = true
159+
```
160+
161+
#### Retry Configuration
162+
163+
Configure retry behavior:
164+
165+
```go
166+
configuration := kbcloud.NewConfiguration()
167+
168+
// Configure retry settings
169+
configuration.RetryConfiguration = common.RetryConfiguration{
170+
EnableRetry: true, // Enable/disable retry
171+
MaxRetries: 3, // Maximum number of retries
172+
RetryInterval: 2, // Base retry interval in seconds
173+
MaxRetryInterval: 30, // Maximum retry interval in seconds
174+
BackOffBase: 2, // Exponential backoff base
175+
RequestTimeout: 30, // Request timeout in seconds
176+
}
177+
```
178+
179+
#### HTTP Client Configuration
180+
181+
Configure HTTP client:
182+
183+
```go
184+
configuration := kbcloud.NewConfiguration()
185+
186+
// Custom HTTP client
187+
configuration.HTTPClient = &http.Client{
188+
Timeout: time.Second * 30,
189+
Transport: &http.Transport{
190+
MaxIdleConns: 10,
191+
MaxIdleConnsPerHost: 10,
192+
IdleConnTimeout: 30 * time.Second,
193+
},
194+
}
195+
196+
// Skip TLS verification (not recommended for production)
197+
ctx := context.WithValue(
198+
context.Background(),
199+
common.ContextInsecureSkipVerify,
200+
true,
201+
)
202+
```
203+
204+
#### User Agent
205+
206+
Configure custom user agent:
207+
208+
```go
209+
configuration := kbcloud.NewConfiguration()
210+
configuration.UserAgent = "MyApp/1.0.0"
211+
```
212+
213+
#### Default Headers
214+
215+
Add default headers to all requests:
216+
217+
```go
218+
configuration := kbcloud.NewConfiguration()
219+
configuration.AddDefaultHeader("Custom-Header", "value")
220+
```
221+
222+
## Development
223+
224+
### Generate API Client
225+
226+
To regenerate the API client code:
6227

7228
```bash
8229
./generate.sh
9-
```
230+
```
231+
232+
## Contributing
233+
234+
We welcome contributions! Please feel free to submit a Pull Request.
235+
236+
## Acknowledgments
237+
238+
This project's generator is inspired by and built upon the work from [Datadog's API client generator](https://github.com/DataDog/datadog-api-client-go). We are grateful to Datadog for their excellent work and open source contributions.
239+
240+
## License
241+
242+
This library is distributed under the Apache 2.0 license found in the [LICENSE](./LICENSE) file.

‎apecloud‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎api/common/configuration.go‎

Lines changed: 16 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -124,31 +124,14 @@ type RetryConfiguration struct {
124124
// NewConfiguration returns a new Configuration object.
125125
func NewConfiguration() *Configuration {
126126
cfg := &Configuration{
127-
DefaultHeader: make(map[string]string),
128-
UserAgent: getUserAgent(),
129-
Debug: false,
130-
Compress: true,
131-
Servers: ServerConfigurations{
132-
{
133-
URL: "http://127.0.0.1:8080",
134-
Description: "local",
135-
Variables: map[string]ServerVariable{},
136-
},
137-
{
138-
URL: "https://api-dev.apecloud.cn",
139-
Description: "dev",
140-
Variables: map[string]ServerVariable{},
141-
},
142-
{
143-
URL: "https://cloudapi.apecloud.cn",
144-
Description: "demo",
145-
Variables: map[string]ServerVariable{},
146-
},
147-
},
148-
OperationServers: map[string]ServerConfigurations{},
127+
DefaultHeader: make(map[string]string),
128+
UserAgent: getUserAgent(),
129+
Debug: false,
130+
Compress: true,
131+
Servers: ServerConfigurations{},
149132
unstableOperations: map[string]bool{},
150133
RetryConfiguration: RetryConfiguration{
151-
EnableRetry: false,
134+
EnableRetry: true,
152135
BackOffMultiplier: 2,
153136
BackOffBase: 2,
154137
HTTPRetryTimeout: 60 * time.Second,
@@ -269,6 +252,16 @@ func (c *Configuration) ServerURLWithContext(ctx context.Context, endpoint strin
269252
return "", err
270253
}
271254

255+
if len(sc) == 0 {
256+
for k, v := range variables {
257+
sc = append(sc, ServerConfiguration{
258+
URL: v,
259+
Description: k,
260+
Variables: map[string]ServerVariable{},
261+
})
262+
}
263+
}
264+
272265
return sc.URL(index, variables)
273266
}
274267

‎examples/auth/auth.go‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
package auth
2+
3+
import (
4+
"context"
5+
"os"
6+
7+
"github.com/apecloud/kb-cloud-client-go/api/common"
8+
)
9+
10+
// NewAuthContext creates a new context with authentication
11+
func NewAuthContext() context.Context {
12+
ctx := context.WithValue(
13+
context.Background(),
14+
common.ContextDigestAuth,
15+
common.DigestAuth{
16+
UserName: os.Getenv("KB_CLOUD_API_KEY_NAME"),
17+
Password: os.Getenv("KB_CLOUD_API_KEY_SECRET"),
18+
},
19+
)
20+
21+
return context.WithValue(
22+
ctx,
23+
common.ContextServerVariables,
24+
map[string]string{"site": os.Getenv("KB_CLOUD_SITE")},
25+
)
26+
}

0 commit comments

Comments
 (0)