Customize Namespaces

When you're exposing your API to users, you may want to group API methods into namespaces to give your SDK an object-oriented interface. This type of interface can help users to better conceptualize the objects they are manipulating when they use the API.

Default Behavior

By default, Speakeasy will use the tags in your OpenAPI spec as the organizing principles for namespaces. For each tag in your spec, a namespace will be created.

Each method will be then be added to namespaces corresponding with its tags If a method does not have an associated tag, then it will be added to the root sdk class of the generated client library. In the case where multiple tags are associated, the operation will appear as a method in multiple classes.

The example below shows one method added to a namespace, and another left to the default class:

paths:
    /stores:
        get:
        operationId: listStores
        summary: List all stores
        description: Get a list of all stores in the system
        responses:
            "200":
            description: A list of stores
            content:
                application/json:
                schema:
                    type: array
                    items:
                    $ref: "#/components/schemas/Store"
  /pets:
    get:
      operationId: listPets
      summary: List all pets
      description: Get a list of all pets in the system
      tags:
        - pets
      responses:
        "200":
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Pet"
tags:
  - name: pets
    description: Everything about Pets

The generated SDK will have methods invocable like so:

// ListPets - List all pets
// Get a list of all pets in the system
sdk.Pets.ListPets()
sdk.ListStores()

Define Namespaces Without Tags

Sometimes the tags in an OpenAPI spec may already be used for an unrelated purpose (for example autogenerating documentation). In this scenario, you may want to use something other than tags to organize your methods.

For this scenario, we support a x-speakeasy-group field which allows you to define custom namespaces. This field can be added to any operation in your OpenAPI spec. If added, the tags for that method will be ignored and the value of x-speakeasy-group will instead define the namespace for that method:

paths:
  /pets:
    get:
      operationId: listPets
      summary: List all pets
      description: Get a list of all pets in the system
      tags:
        - animals
      x-speakeasy-group: pets
      responses:
        "200":
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Pet"
tags:
  - name: pets
    description: Everything about Pets

The generated SDK will have a method invocable like so:

// ListPets - List all pets
sdk.Pets.ListPets()

Ignore Multiple Tags

To disable, simply modify your SDK's gen.yaml file and add the following line:

# ...
generation:
  tagNamespacingDisabled: true

Similarly, you may want to alter the default namespacing behaviour to prevent a method with multiple tags being added to multiple namespaces. To do so, you can add an additional config to your gen.yaml:

# ...
generation:
  singleTagPerOp: true

When singleTagPerOp is true, operations will only be added to the first tag associated to the method.