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

Info Icon

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.