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.0info: title: Test version: 0.0.1servers: - url: https://httpbin.orgx-speakeasy-globals: parameters: - name: customerId in: path schema: type: stringpaths: /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.0info: title: Test version: 0.0.1servers: - url: https://httpbin.orgx-speakeasy-globals: parameters: - $ref: '#/components/parameters/CustomerId'paths: /api/{customerId}: get: operationId: getTest parameters: - $ref: '#/components/parameters/CustomerId' responses: "200": description: OKcomponents: 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.0info: title: Test version: 0.0.1servers: - url: https://httpbin.orgx-speakeasy-globals: parameters: - name: customerId in: path schema: type: string x-speakeasy-globals-hidden: true # This will hide the global parameter from all operationspaths: /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.