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:


paths:
  /bar_locations:
    get:
    operationId: listLocations
    summary: List all locations of the Speakeasy bar
    description: Get a list of all the bars being run by Speakeasy
    responses:
      "200":
        description: A list of bars
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/BarLocation"
  /drinks:
    get:
      operationId: listDrinks
      summary: List all drinks
      description: Get a list of all drinks served by the bar
      tags:
        - drinks
      responses:
        "200":
          description: A list of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
tags:
  - name: drinks
    description: Everything about our Drinks on offer

The generated SDK will include methods that can be invoked as follows:


// Method added into the Drinks namespace
sdk.Drinks.ListDrinks()
// Default method
sdk.ListLocations()

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:


paths:
  /drinks/{drink_type}/get_vintage:
    get:
      operationId: getVintage
      summary: Check the vintage of the wine
      description: Get the vintage of a drink served by the bar
      parameters:
        - name: drink_type
          in: path
          description: The type of drink
          required: true
          schema:
            type: string
      tags:
        - drinks
      x-speakeasy-group: wine
      responses:
        "200":
          description: A list of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
tags:
  - name: drinks
    description: Everything about Drinks on offer

The generated SDK will include a method, which can be invoked as follows:


// GetVintage - get the vintage of the wine
sdk.wine.GetVintage("wine")

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:


// Get the Vintage of a specified wine.
sdk.Drinks.Wine.GetVintage("wine")

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: