You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+78-9Lines changed: 78 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,13 +8,13 @@ The Speakeasy Go SDK for evaluating API requests/responses. Compatible with any
8
8
9
9
## Requirements
10
10
11
-
Supported frameworks:
11
+
Supported routers:
12
12
13
13
* gorilla/mux
14
14
* go-chi/chi
15
15
* http.DefaultServerMux
16
16
17
-
We also support custom Http frameworks:
17
+
We also support custom HTTP frameworks:
18
18
19
19
* gin-gonic/gin
20
20
* labstack/echo
@@ -27,20 +27,26 @@ We also support custom Http frameworks:
27
27
go get github.com/speakeasy-api/speakeasy-go-sdk
28
28
```
29
29
30
-
## Minimum configuration
30
+
###Minimum configuration
31
31
32
32
[Sign up for free on our platform](https://www.speakeasyapi.dev/). After you've created a workspace and generated an API key enable Speakeasy in your API as follows:
33
33
34
-
Configure Speakeasy at the start of your `main()` function with just 2 lines of code:
34
+
Configure Speakeasy at the start of your `main()` function:
35
35
36
36
```go
37
37
import"github.com/speakeasy-api/speakeasy-go-sdk"
38
38
39
39
funcmain() {
40
-
speakeasy.Configure(speakeasy.Configuration {
41
-
APIKey: "YOUR API KEY HERE", // retrieve from Speakeasy API dashboard
40
+
// Configure the Global SDK
41
+
speakeasy.Configure(speakeasy.Config {
42
+
APIKey: "YOUR API KEY HERE", // retrieve from Speakeasy API dashboard.
43
+
ApiID: "YOUR API ID HERE", // custom Api ID to associate captured requests with.
44
+
VersionID: "YOUR VERSION ID HERE", // custom Version ID to associate captured requests with.
42
45
})
43
-
// rest of your program.
46
+
47
+
// Associate the SDK's middleware with your router
48
+
r:= mux.NewRouter()
49
+
r.Use(speakeasy.Middleware)
44
50
}
45
51
```
46
52
@@ -49,7 +55,70 @@ and will be visible on the dashboard next time you log in. Visit our [docs site]
49
55
learn more.
50
56
51
57
52
-
## Optional Arguments
58
+
### Advanced configuration
59
+
60
+
The Speakeasy SDK provides both a global and per Api configuration option. If you want to use the SDK to track multiple Apis or Versions from the same service you can configure individual instances of the SDK, like so:
61
+
62
+
```go
63
+
import"github.com/speakeasy-api/speakeasy-go-sdk"
64
+
65
+
funcmain() {
66
+
// Configure a new instance of the SDK
67
+
sdkInstance:= speakeasy.New(speakeasy.Config {
68
+
APIKey: "YOUR API KEY HERE", // retrieve from Speakeasy API dashboard.
69
+
ApiID: "YOUR API ID HERE", // custom Api ID to associate captured requests with.
70
+
VersionID: "YOUR VERSION ID HERE", // custom Version ID to associate captured requests with.
71
+
})
72
+
73
+
// Associate the SDK's middleware with your router
74
+
r:= mux.NewRouter()
75
+
r.Use(sdkInstance.Middleware)
76
+
}
77
+
```
78
+
79
+
This allows multiple instances of the SDK to be associated with different routers or routes within your service.
80
+
81
+
## Request Matching
82
+
83
+
The Speakeasy SDK out of the box will do its best to match requests to your provided OpenAPI Schema. It does this by extracting the path template used by one of the supported routers or frameworks above for each request captured and attempting to match it to the paths defined in the OpenAPI Schema, for example:
84
+
85
+
```go
86
+
r:= mux.NewRouter()
87
+
r.Use(sdkInstance.Middleware)
88
+
r.HandleFunc("/v1/users/{id}", MyHandler) // The path template "/v1/users/{id}" is captured automatically by the SDK
89
+
```
90
+
91
+
This isn't always successful or even possible, meaning requests received by Speakeasy will be marked as `unmatched`, and potentially not associated with your Api, Version or ApiEndpoints in the Speakeasy Dashboard.
92
+
93
+
To help the SDK in these situations you can provide path hints per request handler that match the paths in your OpenAPI Schema:
53
94
54
-
Coming soon !
95
+
```go
96
+
funcMyHandler(whttp.ResponseWriter, r *http.Request) {
97
+
// Provide a path hint for the request using the OpenAPI Path Templating format: https://swagger.io/specification/#path-templating-matching
98
+
ctrl:= speakeasy.MiddlewareController(req)
99
+
ctrl.PathHint("/v1/users/{id}")
100
+
101
+
// the rest of your handlers code
102
+
}
55
103
```
104
+
105
+
Notes:
106
+
Wildcard path matching in Echo & Chi will end up with a OpenAPI path paramater called {wildcard} which will only match single level values represented by the wildcard. This is a restriction of the OpenAPI spec ([Detail Here](https://github.com/OAI/OpenAPI-Specification/issues/892#issuecomment-281449239)). For example:
And in the above example a path like `/user/1/path/some/sub/path` won't match but `/user/1/path/somesubpathstring` will, as `/` characters are not matched in path paramters by the OpenAPI spec.
111
+
112
+
113
+
114
+
## Capturing Customer IDs
115
+
116
+
To help associate requests with customers/users of your APIs you can provide a customer ID per request handler:
117
+
118
+
```go
119
+
funcMyHandler(whttp.ResponseWriter, r *http.Request) {
120
+
ctrl:= speakeasy.MiddlewareController(req)
121
+
ctrl.CustomerID("a-customers-id") // This customer ID will be used to associate this instance of a request with your customers/users
0 commit comments