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 Schema支持title和description字段：您可以使用它们来完全记录您的架构成员。

使用RAML和REST

1 个答案: