Deprecations

The OpenAPI Specification allows you to deprecate parts of your API, such as methods, parameters, and properties. When you deprecate a part of your API, the SDK will generate relevant deprecated annotations in the code and add a ⚠️ Deprecated label to the SDK docs.

In addition to labeling deprecated parts of an API, Speakeasy extensions are available to customize the messaging of deprecated items.

Deprecate Methods

Deprecate methods in an SDK using the deprecated field in the OpenAPI schema. This will add a deprecated annotation to the generated method and a ⚠️ Deprecated label to the SDK docs.

Use the x-speakeasy-deprecation-message extension to customize the deprecation message displayed in code and the SDK docs.

Use the x-speakeasy-deprecation-replacement extension to specify the method that should be used instead of the deprecated method.


paths:
/drinks:
get:
operationId: listDrinks
deprecated: true
x-speakeasy-deprecation-message: This API will be removed in our next release, please refer to the beverages endpoint.
x-speakeasy-deprecation-replacement: listBeverages
responses:
"200":
description: OK
tags:
- drinks
/beverages:
get:
operationId: listBeverages
responses:
"200":
description: OK
tags:
- beverages


/**
* Get a list of drinks.
*
* @remarks
* Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
*
* @deprecated method: This API will be removed in our next release, please refer to the beverages endpoint. Use listBeverages instead.
*/
async listDrinks(
input: operations.ListDrinksRequest,
options?: RequestOptions
): Promise<operations.ListDrinksResponse> {}

Deprecate Parameters

Deprecate parameters in an SDK using the deprecated field in the OpenAPI schema. This will add a deprecated annotation to the corresponding field in the generated objects and remove the parameter from any relevant usage examples in the SDK docs.

Use the x-speakeasy-deprecation-message extension to customize the deprecation message displayed in code and the SDK docs.


paths:
/drinks:
get:
operationId: listDrinks
summary: Get a list of drinks.
description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
tags:
- drinks
parameters:
- name: ingredient
in: query
description: Filter by ingredient.
required: false
schema:
type: string
example: "vodka"
- name: name
in: query
description: Filter by name.
required: false
deprecated: true
x-speakeasy-deprecation-message: We no longer support filtering by name.
schema:
type: string
example: "martini"
- name: limit
in: query
description: Limit the number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
example: 100


export type ListDrinksRequest = {
/**
* Filter by ingredient.
*/
ingredient?: string | undefined;
/**
* Filter by name.
*
* @deprecated field: We no longer support filtering by name.
*/
name?: string | undefined;
/**
* Limit the number of results.
*/
limit?: number | undefined;
};

Deprecate Properties

Deprecate properties in an SDK using the deprecated field in the OpenAPI schema. This will add a deprecated annotation to the corresponding property in the generated objects and remove the property from any relevant usage examples in the SDK docs.

Use the x-speakeasy-deprecation-message extension to customize the deprecation message displayed in code and the SDK docs.


components:
schemas:
Drink:
type: object
properties:
name:
type: string
stock:
type: integer
productCode:
type: string
sku:
type: string
deprecated: true
x-speakeasy-deprecation-message: We no longer support the SKU property.
required:
- name
- stock
- productCode


export type Drink = {
name: string;
stock: number;
productCode: string;
/**
* @deprecated field: We no longer support the SKU property.
*/
sku?: string | undefined;
};