Configure Your Server

Default Behavior

The OpenAPI spec allows you to define an array of servers that can be used to make requests to the API. These servers are generally used to define different environments available for the API. However, while allowing you to add a description, the spec doesn't provide a strongly-typed way to define which server to use by default (normally the production environment).

openapi: 3.0.3
info:
  title: Example
  version: 0.0.1
servers:
  - url: https://prod.example.com # Used as the default URL by the SDK
    description: Our production environment
  - url: https://sandbox.example.com
    description: Our sandbox environment

The Speakeasy SDK Generator will by default use the first URL in the array, meaning that someone using the SDK will be hitting that first defined server.

Use Templated URLs

Server URLs support templating (opens in a new tab), allowing you to define variables in the URL that can be replaced at runtime.

If your API users have customer-specific URLs that they need to use, you can define a variable in the server URL that users then set in the SDK instantiation. Do this by adding a variables object to the server object in the OpenAPI document:

servers:
  url: https://{customer}.yourdomain.com
    variables:
      customer:
        default: api
        description: The name of the customer sending API requests.

Then your customer will set the appropriate value when instantiating the SDK:

s := sdk.New(
  sdk.WithSecurity(shared.Security{
    BearerAuth: "YOUR_BEARER_TOKEN_HERE",
  }),
  sdk.WithCustomer("CUSTOMER_ID"),
)

Declare Base Server URL

If your OpenAPI document doesn't define any servers (either globally or per operation) or you are using relative paths in the server object, then you will need to define the base server URL in the SDK Generator configuration file. Do this by adding a baseServerUrl property to the gen.yaml file.

# ...
generation:
  baseServerUrl: "https://prod.example.com"

Declare Server at Runtime

The SDK generator will use the first URL in the server object in your spec (or the configured baseServerUrl in the gen.yaml file) as the base URL for all requests, but at runtime, you can configure the SDK to use a different server.

Language-specific examples:

// With a custom address
opts := []sdk.SDKOption{
    sdk.WithServerURL("https://example.com"),
}
// Or with one of the servers in the generated servers array
opts := []sdk.SDKOption{
  sdk.WithServerURL(sdk.Servers[0]),
}
 
s := sdk.New(opts)

CAUTION

If you choose to configure the SDK URL at runtime and relative paths were used in the OpenAPI document, make sure that you account for the baseURL when initializing the SDK server configuration.

Declare Multiple Servers

Passing URLs or index numbers to a URL in the servers array can be cumbersome and doesn't provide a great developer experience. Instead, Speakeasy provides an extension to the OpenAPI spec to define an ID for each server in the servers array. Use the x-speakeasy-server-id property on the server object.

openapi: 3.0.3
info:
  title: Example
  version: 0.0.1
servers:
  - url: https://prod.example.com # Used as the default URL by the SDK
    description: Our production environment
    x-speakeasy-server-id: prod
  - url: https://sandbox.example.com
    description: Our sandbox environment
    x-speakeasy-server-id: sandbox

This extension then enables the below configuration of the SDK at runtime:

// With a constant containing the server ID
opts := []sdk.SDKOption{
    sdk.WithServer(sdk.ServerProd),
}
 
s := sdk.New(opts)

You can pass a map or dict as an optional second argument if the server URLs are templated and the methods to define a specific server URL are still available.