用于 JSON 返回的 REST 服务的 wsdl答案

【问题标题】：wsdl for JSON returned REST services用于 JSON 返回的 REST 服务的 wsdl
【发布时间】：2013-12-29 17:05:19
【问题描述】：

我是基于 REST Web 的服务的新手，并试图了解如何为 JSON 返回的 REST 服务创建合同。

据我了解，任何基于 XML 的 SOAP/REST 服务都会有一个 WSDL 文档。

为基于 JSON 的 REST 服务创建什么文档？

【问题讨论】：

REST web service WSDL?的可能重复
RESTful Services - WSDL Equivalent的可能重复

标签： json rest

【解决方案1】：

REST Web 服务没有像 wsdl 这样的自动解释文档，您需要了解 Web 服务的工作原理，阅读它提供的文档。通常它适用于常见的请求。假设您有一个产品 REST Web 服务，您可以：

GET /products -> read all products
GET /products/1 -> read the product 1
POST /products -> create a new product
PUT /products/1 -> update product 1
DELETE /products/1 -> delete product 1

但您必须知道需要向任何请求发送哪些参数。我希望我很清楚......

【讨论】：

【解决方案2】：

每个 HTTP 响应在 HTTP 标头中都有元数据。这些 HTTP 标头之一是 ContentType。内容类型标识一种媒体类型，它是响应负载必须遵守的合同。媒体类型的规范可以在这里找到http://www.iana.org/assignments/media-types/media-types.xhtml

SOAP 和 HTTP（作为一种应用程序协议）之间的主要区别之一是 SOAP 在设计时定义合同，而对于 HTTP，合同是在响应消息中指定的，因此它可以随时间变化。因此，客户端读取每个响应的内容类型以了解如何处理响应非常重要。

【讨论】：

【解决方案3】：

有 WADL (http://en.wikipedia.org/wiki/Web_Application_Description_Language)，尽管它不像 SOAP 的 WSDL 那样被广泛使用。用 Java EE 编写的 REST 服务会自动将其生成为 .../application.wadl，据我所知，对 PHP 的支持非常差。

【讨论】：

【解决方案4】：

正如其他人提到的那样，RESTful 服务不需要 Web 服务定义，但是如果您想为您的 API 创建类似的东西，则行业标准是 Swagger/OpenAPI，尽管 GraphQL 模式也正在成为事实上的标准。

您还可以探索其他一些选项 (see wikipedia)。

以下是最常用选项的列表：

OpenAPI Spec 中的swagger.json 或 openapi.json 文件
GraphQL Schemas 具有完整规格 here
Postman Collections 可以是published online。
RAML
RSDL

【讨论】：