Skip to content

x-deprecated-reason

Add a GoDoc deprecation warning to a type.

Overview

When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using x-deprecated-reason.

Note

The x-deprecated-reason extension only takes effect when deprecated: true is also set on the field or type.

Example

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-deprecated-reason
components:
  schemas:
    Client:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        id:
          type: number
    ClientWithExtension:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          deprecated: true
          x-deprecated-reason: Don't use because reasons
        id:
          type: number
          # NOTE that this doesn't generate, as no `deprecated: true` is set
          x-deprecated-reason: NOTE you shouldn't see this, as you've not deprecated this field

Generated Code

From here, we now get two different models:

type Client struct {
    Name string   `json:"name" validate:"required"`
    ID   *float32 `json:"id,omitempty"`
}

type ClientWithExtension struct {
    // Deprecated: Don't use because reasons
    Name string   `json:"name" validate:"required"`
    ID   *float32 `json:"id,omitempty"`
}

Notice that because we've not set deprecated: true to the id field, it doesn't generate a deprecation warning.

Use Cases

This extension is useful for:

  • Providing clear migration guidance when deprecating fields
  • Documenting why a field is deprecated
  • Suggesting alternatives to deprecated fields
  • Maintaining API documentation in code

Full Example

You can see this in more detail in the example code.

  • x-go-name - Override the generated name of a field or type