Your API is a contract you're extending to your customers. You need to be able to specify the behavior of a given operation with enough precision that you and y

Your API is a contract you're extending to your customers. You need to be able to specify the behavior of a given operation with enough precision that you and your customer have a good understanding of how it will work. The problem with SOAP/WSDLs is that you break the contract every time you sneeze at the damn thing (adding a field, etc.). Swagger/OpenAPI is generally more permissive, as long as you know what you're doing. API versioning is hard, regardless of the tool you use. Contract-first API design prioritizes predictability over fluidity. The decision on which trade-offs are correct will depend on the context.