To manage API versioning and handling deprecated features in a way that ensures clarity and minimizes disruption for consumers, follow these guidelines that help maintain backward compatibility and provides transparency during major changes:
  • Increment the version for breaking changes—Always update the info.version field whenever a breaking change is introduced. This practice signals to consumers that the API has changed in a way that may require updates on their side.
  • Mark deprecated operations and properties explicitly—Instead of silently removing operations or properties, use the deprecated: true attribute. This approach provides clear communication to API consumers and allows them time to migrate before a major version bump.
  • Add change notes for significant breaking changes—Include a clear change note in the top-level info.description field whenever there is a significant breaking change. This approach ensures that consumers are aware of the impact and can plan accordingly.