使用 RAML 和 REST 的 post 方法的描述

Question

我正在使用 RAML 来指定我的 REST 合同，我想知道是否有某种方法可以更好地用 POST 方法编写合同。

实际上我的 POST 方法显示了以下信息：

<application>
  <grammars/>
  <resources base="http://localhost:8080/ouat-servicesImpl/api">
    <resource path="/topics">
      <method name="POST">
        <request>
          <representation mediaType="application/json"/>
        </request>
        <response>
          <representation mediaType="application/json"/>
        </response>
      </method>
    </resource>
  </resources>
</application>

是否有任何配置可以在表示中暴露更多细节？我尝试了标记示例，但它不起作用

我的 RAML 文档：

schemas:
  - error:       !include schemas/error.json
  - topic:       !include schemas/topic.json
  - topicCreate: !include schemas/topicCreate.json

/topics:
  description: Topic resource.
  displayName: Topic
  post:
    description: Create topic.
    securedBy: [oauth_2_0]
    body:
      application/json:
        schema: topicCreate
    responses:
      201:
        description: Success
        body:
          application/json:
            schema: topic
            example: topic
      400:
        body:
          application/json:
            schema: error
            example: error

我正在使用外部 JSON 文档，例如

{
  "$schema": "http://json-schema.org/schema",
  "type" : "object",
  "description": "The canonical topic representation.",
  "properties" : {
    "id" :       {"type" : "string"},
    "writerID" : {"type" : "string"},
    "text" :     {"type" : "string"}
  },
  "required" : ["id", "text", "writerID"]
}

就我使用了很多 SOAP 合同而言，它期望看到更多信息到请求和响应中

Answer 1

您的 RAML 文件中 POST 方法的规范看起来已经很完整了。

您唯一可以添加的是示例 JSON 实体。

编辑：JSON 架构支持 title 和 description 字段：您可以使用它们来完整记录您的架构成员。

使用 RAML 和 REST 的 post 方法的描述

Description of post methods with RAML and REST

rest

raml