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.0info: title: Test version: 0.0.1servers: - url: https://httpbin.orgsecurity: - basicAuth: []x-speakeasy-name-override: - operationId: ^get.* methodNameOverride: get - operationId: ^post.* methodNameOverride: createpaths: /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.0generation: # ...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 4import { 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 0import { 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();
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 thegen.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