Customize Methods

Change Method Names

Speakeasy uses your OpenAPI schema to infer names for class types, methods, and parameters. However, you can override these names to tailor the generated SDK to your preferences.

The x-speakeasy-name-override extension can be used to override the name of a class, method, or parameter. We’ll detail the various locations this extension can be placed in your OpenAPI schema to override these names at different scopes (globally vs per operation/parameter) in the following sections.

The x-speakeasy-name-override extension may override the generated name for a method generated from an operation. This extension may be used globally if placed at the root of the OpenAPI schema, where all methods with an operationId that matches the provided operationId regex will be overridden with methodNameOverride.

openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
security:
  - basicAuth: []
x-speakeasy-name-override:
  - operationId: ^get.*
    methodNameOverride: get
  - operationId: ^post.*
    methodNameOverride: create
paths:
  /test:
    get:
      operationId: getTest
      responses:
        "200":
          description: OK
    post:
      operationId: postTest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Test"
      responses:
        "200":
        description: OK

Since getTest and postTest match the ^get.* and ^post.* regexes defined by the global x-speakeasy-name-override extension, these method names will be generated as get and create, respectively.

Alternatively, x-speakeasy-name-override may be used at the operation level, where it will override the generated name for the method pertaining only to that operation. This can be combined with the global extension above and will take precedence over it. Consider the same schema shown above but with an operation-level extension added to the get operation:

---
get:
  operationId: getTest
  x-speakeasy-name-override: getRandomTest
  responses:
    "200":
      description: OK

Now, postTest will still be generated as create as before, but getTest will be generated as getRandomTest.

Configuring Method Signatures

Method signatures in your SDK can be customized by controlling how parameters are passed to the method. This can be done through setting the maxMethodParams configuration option in your gen.yaml file.

Here is an example of how to set the maxMethodParams configuration option in your gen.yaml file:

configVersion: 2.0.0
generation:
  # ...
typescript:
  maxMethodParams: 4
  # ...

In the example above, the maxMethodParams configuration option is set to 4. This means that the generated SDK will have a maximum of 4 parameters for each method including the request body parameter.

If the number of parameters for a method exceeds the maxMethodParams configuration option, the generated SDK will use a single request object parameter to encapsulate all the parameters.

You can force the generator to always generate a request object for the SDK by setting maxMethodParams to 0. This can be useful as it will allow request objects to evolve more gracefully and won’t cause a breaking change to your method signature if you need to add more parameters in the future.

Below are examples of SDK with maxMethodParams set to 4 and 0:

// Example of SDK with maxMethodParams set to 4
import { Speakeasybar } from "speakeasy";

async function run() {
const sdk = new Speakeasybar();

    const ingredient = "vodka";
    const name = "martini";
    const limit = 100;

    const result = await sdk.drinks.listDrinks(ingredient, name, limit);

    // Handle the result
    console.log(result);

}

run();

// Example of SDK with maxMethodParams set to 0
import { Speakeasybar } from "speakeasy";

async function run() {
const sdk = new Speakeasybar();

    const result = await sdk.drinks.listDrinks({
        ingredient: "vodka",
        name: "martini",
        limit: 100,
    });

    // Handle the result
    console.log(result);

}

run();

# Example of SDK with maxMethodParams set to 4
import sdk

s = sdk.SDK()


res = s.drinks.list_drinks(ingredient='vodka', name='martini', limit=100)

if res.drinks is not None:
    # handle response
    pass

# Example of SDK with maxMethodParams set to 0
import sdk
from sdk.models import operations

s = sdk.SDK()

req = operations.ListDrinksRequest(
    ingredient='vodka',
    name='martini',
    limit=100,
)

res = s.drinks.list_drinks(req)

if res.drinks is not None:
    # handle response
    pass

// Example of SDK with maxMethodParams set to 4
package main

import (
	"context"
	"log"
	"speakeasy"
)

func main() {
s := speakeasy.New()

    var ingredient *string = speakeasy.String("vodka")

    var name *string = speakeasy.String("martini")

    var limit *int64 = speakeasy.Int64(100)

    ctx := context.Background()
    res, err := s.Drinks.ListDrinks(ctx, ingredient, name, limit)
    if err != nil {
    	log.Fatal(err)
    }
    if res.Drinks != nil {
    	// handle response
    }

}

// Example of SDK with maxMethodParams set to 0
package main

import (
	"context"
	"log"
	"speakeasy"
	"speakeasy/models/operations"
)

func main() {
s := speakeasy.New()

    ctx := context.Background()
    res, err := s.Drinks.ListDrinks(ctx, operations.ListDrinksRequest{
    	Ingredient: speakeasy.String("vodka"),
    	Name:       speakeasy.String("martini"),
    	Limit:      speakeasy.Int64(100),
    })
    if err != nil {
    	log.Fatal(err)
    }
    if res.Drinks != nil {
    	// handle response
    }

}

// Example of SDK with maxMethodParams set to 4
package hello.world;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import org.openapis.openapi.SDK;
import org.openapis.openapi.models.components.*;
import org.openapis.openapi.models.operations.*;
import org.openapis.openapi.models.operations.ListDrinksRequest;
import org.openapis.openapi.models.operations.ListDrinksResponse;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) {
        try {
            SDK sdk = SDK.builder()
                .build();

            ListDrinksResponse res = sdk.drinks().listDrinks()
                .ingredient("vodka")
                .name("martini")
                .limit(100L)
                .call();

            if (res.drinks().isPresent()) {
                // handle response
            }
        } catch (org.openapis.openapi.models.errors.SDKError e) {
            // handle exception
        } catch (Exception e) {
            // handle exception
        }
    }
}

// Example of SDK with maxMethodParams set to 0
package hello.world;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import org.openapis.openapi.SDK;
import org.openapis.openapi.models.components.*;
import org.openapis.openapi.models.operations.*;
import org.openapis.openapi.models.operations.ListDrinksRequest;
import org.openapis.openapi.models.operations.ListDrinksResponse;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) {
        try {
            SDK sdk = SDK.builder()
                .build();

            ListDrinksRequest req = ListDrinksRequest.builder()
                .ingredient("vodka")
                .name("martini")
                .limit(100L)
                .build();

            ListDrinksResponse res = sdk.drinks().listDrinks()
                .request(req)
                .call();

            if (res.drinks().isPresent()) {
                // handle response
            }
        } catch (org.openapis.openapi.models.errors.SDKError e) {
            // handle exception
        } catch (Exception e) {
            // handle exception
        }
    }
}

// Example of SDK with maxMethodParams set to 4
using Openapi;
using Openapi.Models.Operations;
using Openapi.Models.Shared;
using NodaTime;

var sdk = new SDK();

var res = await sdk.Drinks.ListDrinksAsync("vodka", "martini", 100);

// handle response

// Example of SDK with maxMethodParams set to 0
using Openapi;
using Openapi.Models.Operations;
using Openapi.Models.Shared;
using NodaTime;

var sdk = new SDK();

var req = new ListDrinksRequest()
{
Ingredient = "vodka",
Name = "martini",
Limit = 100
};

var res = await sdk.Drinks.ListDrinksAsync(req);

// handle response

The maxMethodParams can also be set via an extension x-speakeasy-max-method-params in your OpenAPI document either globally at the root of the document or at the operation level.

The order of precedence for configuration is as follows:

Operation-level x-speakeasy-max-method-params
Global-level x-speakeasy-max-method-params
maxMethodParams in the gen.yaml file

The configuration in gen.yaml or via the extension at the root of the document will apply to all operations in the document unless overridden by an operation-level extension.

Exclude Parameters From Signatures

To exclude certain parameters from your generated SDK, use the x-speakeasy-ignore extension on the spec.

Here is an example using x-speakeasy-ignore: true to remove a parameter.

paths:
  /test/user/{user_id}:
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      - name: status
        x-speakeasy-ignore: true
        in: query
        required: true
        schema:
          type: string
    get:
      operationId: getUser
      responses:
        "200":
          description: OK
          ...

Exclude Methods From SDK

When generating an SDK you may want to exclude certain methods from being included in your SDK. This is can be indicated on the spec with the x-speakeasy-ignore extension.

Here is an example with several instances of x-speakeasy-ignore: true being used across the specification.

paths:
  /test:
    get:
      x-speakeasy-ignore: true
      operationId: getTest
      responses:
        "200":
          description: OK