Define Global Parameters

Use the x-speakeasy-globals extension to define parameters that can be configured globally on the main SDK instance. These parameters will be automatically populated for any operations that use them. This is especially useful for configurations that are required across all operations, such as customer IDs.


openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
x-speakeasy-globals:
  parameters:
    - name: customerId
      in: path
      schema:
        type: string
paths:
  /api/{customerId}:
    get:
      operationId: getTest
      parameters:
        - name: customerId # If this matches a global parameter it will be populated automatically
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: OK

If the name, in, and schema values of a global parameter match a parameter in an operation, the global parameter will be populated automatically. If the global parameter is not used in the operation, it will be ignored.

Preferred Method: Using Component References

The preferred way to define global parameters is by referencing a component. This ensures consistency and reusability:


openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
x-speakeasy-globals:
  parameters:
    - $ref: '#/components/parameters/CustomerId'
paths:
  /api/{customerId}:
    get:
      operationId: getTest
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        "200":
          description: OK
components:
  parameters:
    CustomerId:
      name: customerId
      in: path
      schema:
        type: string

Supported Parameter Types

Global parameters can be used with in: query, in: path, or in: header fields. Only primitive types such as string, number, integer, boolean, and enums are supported for global parameters.

The global parameter definitions in the sample above will generate the following output:


import { Speakeasybar } from "speakeasy";
async function run() {
    const sdk = new Speakeasybar({
        customerId: "1291fbe8-4afb-4357-b1de-356b65c417ca", // customerId can be set when instantiating the SDK and is used for all compatible operations
    });
    const result = await sdk.getCustomer({});
    // Handle the result
    console.log(result);
}
run();

Hiding Global Parameters From Method Signatures

Limited Support

Currently, this feature is only supported in Go, Python, and Typescript.

To hide global parameters from method signatures, use the x-speakeasy-globals-hidden extension. This is useful when you want the global parameter to be set only once during SDK instantiation and not be overridden in individual operations.


openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
x-speakeasy-globals:
  parameters:
    - name: customerId
      in: path
      schema:
        type: string
      x-speakeasy-globals-hidden: true # This will hide the global parameter from all operations
paths:
  /api/{customerId}:
    get:
      operationId: getTest
      parameters:
        - name: customerId
          in: path
          schema:
            type: string
          required: true
      responses:
        "200":
          description: OK

You can control the visibility of the global parameter by setting x-speakeasy-globals-hidden to true on the global parameter definition or on the operation parameter that matches the global parameter. Setting it globally hides the parameter from all operations. Setting it on a specific operation hides it only for that operation.