我看到的大多数 REST 接口都是用一个简单的网页描述的，描述了 URL、方法、接受的输入和返回的结果。例如Amazon S3或Twitter API文档。
对于亚马逊或 Twitter 来说，人类可读性显然已经足够了。但是，是否有任何公司以机器可读的格式描述 REST API？如果是，是哪些？
WSDL 2.0 声明能够描述 REST。WADL是为描述 REST 服务而显式创建的。WSDL 2.0 和 WADL 似乎都有一个相当小的后续 atm，并且对于创建和维护描述文档的努力似乎没有什么回报。通过识别现实生活中的例子，基本上可以验证或否定这个假设。
您是否使用 WSDL/WADL 来描述您的服务？你是否依赖 WSDL/WADL 来消费别人的服务？您选择的工具目前是否支持其中任何一种？是否有任何可以使用的广泛使用的 REST 服务示例，并以机器可读格式详细说明？
是的你应该。您将能够使用一组支持 WADL 的工具生成您的客户端代码、测试和文档。一些例子可以在这里找到。另外，我认为您应该坚持使用 WADL，而不是 WSDL 2.0，因为它不那么冗长且更简单（恕我直言）。事实上，在 WADL 中，您只需使用 WADL XML 语法就可以准确地描述用户在文档页面上看到的内容。顺便说一句，这就是为什么为 WADL 编写基于 XSLT 的文档生成器如此容易的原因。
以下只是我个人的看法：
我认为 WADL 类似于 html 页面的站点地图。站点地图在理论上被认为是一种很好的做法，但很少被实施，甚至很少被人们使用。
我认为原因很简单——在网站上闲逛并按下战略性放置的按钮通常比浏览复杂的地图更有价值。
REST API 方法不需要正式的描述。因此，如果 API 是经过深思熟虑创建的，那么只需遵循“home”RESTful 资源的策略性放置的 uri 链接，就很容易发现所有资源。
The most popular usage of WSDL (and WADL in the same way) is code generation. It sure helps speed up development, but nothing can replace plain old documentation. For humans and not for machines.
这里有一个鸡/蛋的现象。如果没有生产或使用它的工具，WADL 将毫无用处。除非网站发布 WADL，否则这些工具毫无用处。等等
对我来说，亚马逊模式运作良好。根据您的受众，您将在制作样本的努力中获得更多回报，包括剪辑 od 样本对话框（request1 在网络上看起来像什么，响应 1 相同，然后是请求 2，响应 2 等），以及各种代码对您很重要的语言。如果要转至机器可读的定义，则可以使用 XSD（如果它是 XML 消息格式）。显然这不是 WADL，但结合您的英文描述，它可能会为开发人员提供一些额外的实用程序。
机器可读的 REST API 定义有什么好处？
REST 的重点是 API 相对简单且易于理解。自然语言对此非常有效。
如果您在说“API 定义”时指的是“API 类型定义”，那么提供元数据可能会有一些价值。然而，这只是 API 定义的一部分。
拥有“机器可读”的 API 很容易重复 API 源代码，违反了 DRY 原则。
编写 REST 动词的作用和 URI 是什么的英文描述通常更简单。将通过 JSON（或 YAML 或 JAXB）编组的类型作为源代码发送。那是完美的机器可读 API——消息对象类的实际工作源。