java - REST 客户端 API 数据类型

Question

我的基本假设是，对于 SOAP 网络服务，提供的 WSDL 将包含描述发送和接收的数据类型的 XSD。在用 Java 开发客户端时，可以使用 wsimport 等工具生成对应于 WSDL 元素的类，尤其是复杂数据类型。这使 SOAP 客户端的开发人员无需创建表示返回类型(和/或复杂参数)的类。

相比之下，对于 REST api，我通常不会看到 -

1. WSDL 2.0 http://www.ibm.com/developerworks/webservices/library/ws-restwsdl/
2. WADL http://www.w3.org/Submission/wadl/
3. (如果服务器和客户端都是 Java)只提供在服务器端使用的相同 JAXB 类
4. XSD

所以我的问题是 - 作为 REST 服务器端 API 的作者，向客户端提供相关数据类型的最佳方式是什么？

Answer 1

由于 REST API 的用户很可能是开发人员，因此没有唯一的答案。作为一名开发人员，我认为使用我最喜欢的编程语言编写的客户端库(由 API 的创建者开发)是最佳选择。

您已经提到了用于文档的 WADL，但还有:

• Swagger :可能是最成熟和功能最丰富的 REST API 文档方法。它包括一个可嵌入的 API 浏览器。
• RAML :基于 YAML 的 REST API 规范标准。围绕此创建了多个项目，例如一个(实验性的)JAX-RS 生成器，包括带注释的 Jackson 类或 raml2html 转换器。

两种选择都支持 Json Schema 的 XSD。通过使用其中之一，您应该能够创建对所有可能的 API 用户都有帮助的文档。