# Deprecations

The OpenAPI Specification allows deprecating parts of an API, such as methods, parameters, and properties. When deprecating a part of an 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.

```yaml
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
```

<CodeWithTabs client:visible
  tabs={[
    {
      label: "TypeScript",
      language: "typescript",
      code: `/**
       * 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> {}`,
    },
    {
      label: "Python",
      language: "python",
      code: `def list_drinks(self, request: operations.ListDrinksRequest) -> operations.ListDrinksResponse:
          r"""Get a list of drinks.
          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 list_beverages instead.
          """`,
    },
    {
      label: "Go",
      language: "go",
      code: `  // ListDrinks - Get a list of drinks.
      // 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.
      func (s *Drinks) ListDrinks(ctx context.Context, request operations.ListDrinksRequest) (*operations.ListDrinksResponse, error) {}`,
    },
    {
      label: "Java",
      language: "java",
      code: ` /**
    * Get a list of drinks.
    * Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
    * @param request The request object containing all of the parameters for the API call.
    * @return The response from the API call.
    * @throws Exception if the API call fails.
    * @deprecated method: This API will be removed in our next release, please refer to the beverages endpoint. Use listBeverages instead.
    */
  @Deprecated
  public org.openapis.openapi.models.operations.ListDrinksResponse listDrinks(
          org.openapis.openapi.models.operations.ListDrinksRequest request) throws Exception {}`,
    },
    {
      label: "C#",
      language: "csharp",
      code: `[Obsolete("This method will be removed in a future release, please migrate away from it as soon as possible. Use ListBeverages instead")]
public async Task<ListDrinksResponse> ListDrinksAsync() {}`,
    },
    {
      label: "PHP",
      language: "php",
      code: `/**
       * Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
       * @param request The request object containing all of the parameters for the API call.
       * @return The response from the API call.
       * @throws OpenAPI\\OpenAPI\\SDKException
       * @deprecated  method: This API will be removed in our next release, please refer to the beverages endpoint. Use listBeverages instead.
       */
      public function listDrinks(Shared\\ListDrinksRequest $request): ListDrinksResponse`,
    },
    {
      label: "Ruby",
      language: "ruby",
      code: ` # Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      # @param request [Models::Shared::ListDrinksRequest] The request object containing all of the parameters for the API call.
      # @return [ListDrinksResponse] The response from the API call.
      # @raise [Models::Errors::APIError]
      # @deprecated This API will be removed in our next release, please refer to the beverages endpoint. Use list_beverages instead.
      def list_drinks(request)`,
}

]}
/>

## 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.

```yaml
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
```

<CodeWithTabs client:visible
  tabs={[
    {
      label: "TypeScript",
      language: "typescript",
      code: `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;
  };`,
    },
    {
      label: "Python",
      language: "python",
      code: `@dataclasses.dataclass
class ListDrinksRequest:
ingredient: Optional[str] = dataclasses.field(default=None, metadata={'query_param': { 'field_name': 'ingredient', 'style': 'form', 'explode': True }})
r"""Filter by ingredient."""
name: Optional[str] = dataclasses.field(default=None, metadata={'query_param': { 'field_name': 'name', 'style': 'form', 'explode': True }})
r"""Filter by name.

    Deprecated field: We no longer support filtering by name.
    """
    limit: Optional[int] = dataclasses.field(default=None, metadata={'query_param': { 'field_name': 'limit', 'style': 'form', 'explode': True }})
    r"""Limit the number of results."""`,
    },
    {
      label: "Go",
      language: "go",
      code: `type ListDrinksRequest struct {
    // Filter by ingredient.
    Ingredient *string \`queryParam:"style=form,explode=true,name=ingredient"\`
    // Filter by name.
    //
    // Deprecated field: We no longer support filtering by name.
    Name *string \`queryParam:"style=form,explode=true,name=name"\`
    // Limit the number of results.
    Limit *int64 \`queryParam:"style=form,explode=true,name=limit"\`

}`,
    },
    {
      label: "Java",
      language: "java",
      code: `public class ListDrinksRequest {

    /**
     * Filter by ingredient.
     */
    @SpeakeasyMetadata("queryParam:style=form,explode=true,name=ingredient")
    private Optional<? extends String> ingredient;

    /**
     * Filter by name.
     * @deprecated field: We no longer support filtering by name.
     */
    @SpeakeasyMetadata("queryParam:style=form,explode=true,name=name")
    @Deprecated
    private Optional<? extends String> name;

    /**
     * Limit the number of results.
     */
    @SpeakeasyMetadata("queryParam:style=form,explode=true,name=limit")
    private Optional<? extends Long> limit;

}`,
    },
    {
      label: "C#",
      language: "csharp",
      code: `public class ListDrinksRequest
{

    /// <summary>
    /// Filter by ingredient.
    /// </summary>
    [SpeakeasyMetadata("queryParam:style=form,explode=true,name=ingredient")]
    public string? Ingredient { get; set; }

    /// <summary>
    /// Limit the number of results.
    /// </summary>
    [SpeakeasyMetadata("queryParam:style=form,explode=true,name=limit")]
    public long? Limit { get; set; }

    /// <summary>
    /// Filter by name.
    /// </summary>
    [Obsolete("This field will be removed in a future release, please migrate away from it as soon as possible")]
    [SpeakeasyMetadata("queryParam:style=form,explode=true,name=name")]
    public string? Name { get; set; }

}`,
    },
    {
      label: "PHP",
      language: "php",
      code: `class ListDrinksRequest
{

    /**
     * Filter by ingredient.
     * @var ?string $ingredient
     */
    #[SpeakeasyMetadata('queryParam:style=form,explode=true,name=ingredient')]
    private ?string ingredient;

    /**
     * Filter by name.
     * @var ?string name
     * @deprecated field: We no longer support filtering by name.
     */
    #[SpeakeasyMetadata('queryParam:style=form,explode=true,name=name')]
    private ?string name;

    /**
     * Limit the number of results.
     * @var ?float limit
     */
    #[SpeakeasyMetadata("queryParam:style=form,explode=true,name=limit")]
    private ?float limit;

}`,
    },
    {
      label: "Ruby",
      language: "ruby",
      code: `class ListDrinksRequest
include Crystalline::MetadataFields

    # Filter by ingredient.
    field :ingredient, Crystalline::Nilable.new(::String), { 'queryParam': {'style': 'form', 'explode': true, 'name': 'ingredient'} }

    # Filter by name.
    field :name, Crystalline::Nilable.new(::String), { 'queryParam': {'style': 'form', 'explode': true, 'name': 'name'} }

    # Limit the number of results
    field :limit, Crystalline::Nilable.new(::Float), { 'queryParam': {'style': 'form', 'explode': true, 'name': 'limit'} }

end`,
}
]}
/>

## 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.

```yaml
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
```

<CodeWithTabs client:visible
  tabs={[
    {
      label: "TypeScript",
      language: "typescript",
      code: `export type Drink = {
      name: string;
      stock: number;
      productCode: string;
      /**
       * @deprecated field: We no longer support the SKU property.
       */
      sku?: string | undefined;
  };`,
    },
    {
      label: "Python",
      language: "python",
      code: `@dataclass_json(undefined=Undefined.EXCLUDE)
  @dataclasses.dataclass
  class Drink:
      name: str = dataclasses.field(metadata={'dataclasses_json': { 'letter_case': utils.get_field_name('name') }})
      stock: int = dataclasses.field(metadata={'dataclasses_json': { 'letter_case': utils.get_field_name('stock') }})
      product_code: str = dataclasses.field(metadata={'dataclasses_json': { 'letter_case': utils.get_field_name('productCode') }})
      sku: Optional[str] = dataclasses.field(default=None, metadata={'dataclasses_json': { 'letter_case': utils.get_field_name('sku'), 'exclude': lambda f: f is None }})
      r"""Deprecated field: We no longer support the SKU property."""`,
    },
    {
      label: "Go",
      language: "go",
      code: `type Drink struct {
      Name        string \`json:"name"\`
      Stock       int64  \`json:"stock"\`
      ProductCode string \`json:"productCode"\`
      // Deprecated field: We no longer support the SKU property.
      Sku *string \`json:"sku,omitempty"\`
}`,
    },
    {
      label: "Java",
      language: "java",
      code: `public class Drink {

      @JsonProperty("name")
      private String name;

      @JsonProperty("stock")
      private long stock;

      @JsonProperty("productCode")
      private String productCode;

      /**
      * @deprecated field: We no longer support the SKU property.
      */
      @JsonInclude(Include.NON_ABSENT)
      @JsonProperty("sku")
      @Deprecated
      private Optional<? extends String> sku;
    }`,
    },
    {
      label: "C#",
      language: "csharp",
      code: `public class Drink

{
[SpeakeasyMetadata("queryParam:name=name")]
public string Name { get; set; } = default!;

      [SpeakeasyMetadata("queryParam:name=productCode")]
      public string ProductCode { get; set; } = default!;

      [Obsolete("This field will be removed in a future release, please migrate away from it as soon as possible")]
      [SpeakeasyMetadata("queryParam:name=sku")]
      public string? Sku { get; set; }

      [SpeakeasyMetadata("queryParam:name=stock")]
      public long Stock { get; set; } = default!;

}`,
    },
    {
      label: "PHP",
      language: "php",
      code: `class Drink
  {
      /**
        * @var ?string $name
        */
      #[SpeakeasyMetadata("queryParam:name=name")]
      public ?string $name = null;

      /**
        * @var string productCode
        */
      #[SpeakeasyMetadata("queryParam:name=productCode")]
      public string $productCode;

      /**
      * @var ?string sku
      * @deprecated field: This field will be removed in a future release, please migrate away from it as soon as possible
      */
      #[SpeakeasyMetadata("queryParam:name=sku")]
      public ?string sku = null;

      /**
        * @var float stock
        */
      #[SpeakeasyMetadata("queryParam:name=stock")]
      public float stock;
  }`,
    },
    {
      label: "Ruby",
      language: "ruby",
      code: `class Drink
include Crystalline::MetadataFields

    field :name, ::String, { 'queryParam': {'name':'name'} }
    field :product_code, ::String, { 'queryParam': {'name':'product_code'} }

    # @deprecated field: This field will be removed in a future release, please migrate away from it as soon as possible

    field :sku, Crystalline::Nilable.new(::String), { 'queryParam': {'name':'sku'} }
    field :stock, ::Float, { 'queryParam': {'name':'stock'} }

end`,
}
]}
/>