Configure your Server

Default Behavior

The OpenAPI spec allows you 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.

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. This is done by adding a baseServerUrl property to the gen.yaml file.

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

Declare Server At Runtime

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

Language-specific examples:

Go

// 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)

Python

s = sdk.SDK()

# With a custom address
s.config_server_url("https://example.com")
# or with one of the servers in the generated servers array
s.config_server_url(sdk.SERVERS[0])

Typescript

// With a custom address
const opts = [WithServerURL("https://example.com")];
// or with one of the servers in the generated servers array
const opts = [WithServerURL(Servers[0])];

const s = new SDK(opts);

Java

SDK.Builder builder = SDK.builder();

// With a custom address
builder.setServerURL("https://example.com");
// or with one of the servers in the generated servers array
builder.setServerURL(SDK.SERVERS[0]);

SDK sdk = builder.build();

caution

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

Server URLs also support templating to allow you to define variables in the URL that can be replaced at runtime. For example, if you have a server URL like https://{variable}.example.com you can replace the {variable} variable with a value like below:

Go

// Pass a map of variables to replace those matching the server URL
opts := []sdk.SDKOption{
    sdk.WithServerURL("https://{variable}.example.com", map[string]string{
        "variable": "value",
    }),
}

Python

# Pass a dict of variables to replace those matching the server URL
s.config_server_url("https://{variable}.example.com", {"variable": "value"})

Typescript

// With an object of variables to replace those matching the server URL
const opts = [
  WithServerURL("https://{variable}.example.com", {
    variable: "value",
  }),
];

Java

SDK.Builder builder = SDK.builder();

// With an object of variables to replace those matching the server URL
builder.setServerURL("https://{variable}.example.com", new HashMap<String, String>() {{
    put("variable", "value");
}});

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. To make this easier, Speakeasy provides an extension to the OpenAPI spec that allows you to define an ID for each server in the Servers array. This can be done using 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:

Go

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

s := sdk.New(opts)

Python

s = sdk.SDK()

# With a constant containing the server ID
s.config_server(sdk.SERVER_PROD)

Typescript

// With a constant containing the server ID
const opts = [WithServer(ServerProd)];

Java

SDK.Builder builder = SDK.builder();

// With an enum containing the server ID
builder.setServer(SDK.Servers.PROD);

A map/dict can still be passed as an optional second argument if the server URLs are templated and the methods to define a specific server URL are also still available.