Skip to main content

Provide Path Hints

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 the Mapping annotation for your controller handlers and attempting to match it to the paths defined in the OpenAPI Schema, for example:

r := mux.NewRouter()
r.Use(sdkInstance.Middleware)
r.HandleFunc("/v1/users/{id}", MyHandler) // The path template "/v1/users/{id}" is captured automatically by the SDK

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. This normally happens if your path contains regex patterns or is a catch all path and your handler parses the routes manually. To help the SDK in these situations you can provide path hints per request handler that match the paths in your OpenAPI Schema:

func MyHandler(w http.ResponseWriter, r *http.Request) {
// Provide a path hint for the request using the OpenAPI Path Templating format: https://swagger.io/specification/#path-templating-matching
ctrl := speakeasy.MiddlewareController(req)
ctrl.PathHint("/v1/users/{id}")

// the rest of your handlers code
}
note

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). For example:

chi template: /user/{id}/path/* => openapi template: /user/{id}/path/{wildcard}

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 parameters by the OpenAPI spec.