Define Global Parameters

You can use the x-speakeasy-globals extension to define parameters that can be configured globally on the main SDK instance and populated automatically for any operations that use them. This is useful for global configuration that is required for all operations, for example, 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.

The prefered way of defining globals though is by using a reference to a component:


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

Globals work with in: query, in: path or in: header. Only the primitive types string, number, integer, and boolean and enums can be used to define 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

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

This can be done by setting x-speakeasy-globals-hidden to true on the global parameter definition or the operation parameter that matches the global parameter. Setting globally will hide the global parameter from all operations that use it, otherwise, it will only hide it for that operation.


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