How do you deprecate an API operation in OpenAPI?

OpenAPI supports a simple boolean deprecated field that can be set on an individual operation (or on a whole schema, parameter, or property) to signal that it's still functional but shouldn't be used for new development, without removing it from the spec entirely while consumers migrate away.

paths:
  /users/legacy-search:
    get:
      deprecated: true
      summary: Search users (deprecated, use /users/search instead)

Tools like Swagger UI render deprecated operations with a visual indicator (typically strikethrough text or a warning badge) so consumers browsing the documentation notice the deprecation at a glance rather than having to read every description carefully to catch it, and code generators can optionally emit deprecation warnings (like Java's @Deprecated annotation) on the corresponding generated method.

Good practice alongside setting deprecated: true is documenting the replacement directly in the operation's description, as shown above, since the boolean flag alone tells a consumer something is going away but not what to migrate to; pairing the flag with clear migration guidance is what actually helps consumers act on the deprecation rather than just being aware of it.