Designing and managing APIs for microservices

You've learned that each microservice should only be invoked from its interface. But when we design interfaces for our services, how can we let others know how to use them? Considering the fact that different teams may be managing different microservices and that microservices can be exposed as public APIs for others to consume, how can we implement a "contract" so that everyone knows what to expect? Better yet, is there a standard used by many others that we can also adhere to? That's what an API definition language such as OpenAPI (previously Swagger) helps accomplish. The OpenAPI specification (https://www.openapis.org/) is a "broadly adopted industry standard for describing modern APIs," as stated on its website. It's a vendor-neutral description format developed under the Linux Foundation. Another API specification language also backed by a large open source community is RAML (https://raml.org/),...