Deprecations
The OpenAPI specification allows you to deprecate various 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.
Along with this there are various Speakeasy extensions available to customize the messaging of the deprecated items.
Deprecate Methods
You can deprecate methods in your SDK by using the deprecated
field in your OpenAPI schema. This will add a deprecated
annotation to the generated method and add a ⚠️ Deprecated
label to the SDK docs.
Using x-speakeasy-deprecation-message
will allow you to customize the deprecation message that is displayed in code and in the SDK docs.
While using x-speakeasy-deprecation-replacement
will allow you 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
You can deprecate parameters in your SDK by using the deprecated
field in your 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.
Using x-speakeasy-deprecation-message
will allow you to customize the deprecation message that is displayed in code and in 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
You can deprecate properties in your SDK by using the deprecated
field in your 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.
Using x-speakeasy-deprecation-message
will allow you to customize the deprecation message that is displayed in code and in 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;};