Customize Namespaces
When exposing an API to users, grouping API methods into namespaces creates an object-oriented SDK interface. This type of interface helps users better conceptualize the objects they are manipulating when using the API.
Default Behavior
By default, Speakeasy uses the tags
in the OpenAPI spec as organizing principles for namespaces. For each tag
in the spec, Speakeasy creates a namespace.
Each method will then be added to namespaces corresponding with its tags
. If a method does not have an associated tag
, it will be added to the root SDK class of the generated client library. If a method has multiple tags associated with it, the operation will appear as a method in multiple classes.
The following example illustrates the method sdk.Drinks.ListDrinks()
assigned to the Drinks
namespace and another method sdk.ListLocations()
kept in the default class:
The generated SDK will include methods that can be invoked as follows:
Define Namespaces Without Tags x-speakeasy-group
Sometimes the tags
in an OpenAPI spec may already be used for an unrelated purpose (for example, autogenerating documentation). In this scenario, using something other than tags
to organize methods may be necessary.
The x-speakeasy-group
field allows defining custom namespaces. Add this field to any operation in the OpenAPI spec to override any tags
associated with that method. For example:
The generated SDK will include a method, which can be invoked as follows:
Define Multi-Level Namespaces
Use tags
or the x-speakeasy-group
extension to define nested namespaces for operations using .
notation. There is no limit to the number of levels that can be defined.
The generated SDK will include a method, invoked as follows:
Multiple Namespaces
If you want to add a method to multiple namespaces, list multiple values in tags
or the x-speakeasy-group
extension. Both accept an array of values:
The generated SDK will include methods that can be invoked as follows: