Adopt
If an API isn't documented (OpenAPI or AsyncAPI) and published (Backstage or external developer portal), it effectively doesn't exist for the consumer. It shifts documentation from a "nice-to-have" chore to a core architectural requirement.
Whether you are dealing with REST (OpenAPI) or event-driven patterns (AsyncAPI), sticking to this principle ensures:
- Contract First: The API definition serves as the single source of truth.
- Reduced Friction: Developers can self-serve rather than hunting down engineers for "how this works."
- Interoperability: Standardized schemas allow different systems to talk to each other without custom glue code.
More info: https://www.openapis.org/
Platform: flowbird, global-platform