This is part of the Api-First paradigm. Instead of your controllers/handlers being the authoritative "Truth", the API spec is. You and your team spend time arg

This is part of the Api-First paradigm. Instead of your controllers/handlers being the authoritative "Truth", the API spec is. You and your team spend time arguing/debating the API from the perspective of a user. "I need X data from Y service", etc. The document then becomes the "blueprint" for your system. Think of it as TDD but viewed from a different angle. In a microservices system, this has a tremendous amount of advantages, including being able to codegen your handlers and models, maintain consistency across the entire API, unified api documentation, increase testability of your controller/handler interface, and more.