POST RAML 中的参数支持

Question

想问一下RAML. And if there is - what is the syntax. I've browsed spec 0.8 and spec 1.0中有没有对POST参数的大致支持（其实我是绑定0.8的，因为很多工具都不支持1.0还没有）。我没有找到 POST 参数支持，但也许我只是错过了一些东西。

那么 POST 参数是什么意思？这些可以是两者之一（抱歉，我不知道他们的正式名称，如果有的话）：

HTTP plain parameters,key=value,每个参数一行，如

name=John Doe amount=5 这不是很方便（例如没有嵌套）
参数作为JSON对象，只是一个允许所有语法的JSON（服务器端需要解析这个json);如：

{"name":"John Doe","amount":"5"}

不同的服务器端 API 实现使用第一个或第二个。无论如何，RAML 如何支持这些？

Answer 1

Post参数可以用JSON Schema

表示

一个简单的 RAML 0.8 示例：

#%RAML 0.8
title: Api
baseUri: /
schemas:
  - Invoice: |
    { 
      "$schema": "http://json-schema.org/draft-03/schema",
      "type": "object",
      "properties": {
        "Id": { "type": "integer"},
        "Name": { "type": "string"},
        "Total": { "type": "number"}
      }
    }
/invoices:
  post:
    body:
      application/json:
        schema: Invoice

Answer 2

@Pedro has covered option 2, so here is option 1. Based on the discussion in the comments, it seems the encoding used is application/x-www-form-urlencoded.

您需要使用formParameters。

示例：

  post:
    description: The POST operation adds an object to a specified bucket using HTML forms.
    body:
      application/x-www-form-urlencoded:
        formParameters:
          AWSAccessKeyId:
            description: The AWS Access Key ID of the owner of the bucket who grants an Anonymous user access for a request that satisfies the set of constraints in the Policy.
            type: string
          acl:
            description: Specifies an Amazon S3 access control list. If an invalid access control list is specified, an error is generated.
            type: string

参考：https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#web-forms

Answer 3

如参考文献中所示 https://github.com/raml-org/raml-spec/wiki/Breaking-Changes:

对于 raml 0.8:

body:
  application/x-www-form-urlencoded:
    formParameters:
      name:
        description: name on account
        type: string
        example: Naruto Uzumaki
      gender:
        enum: ["male", "female"]

在 raml 1.0 中等价于：

body:
  application/x-www-form-urlencoded:
    properties:
      name:
        description: name on account
        type: string
        example: Naruto Uzumaki
      gender:
        enum: ["male", "female"]

所以它改变的是属性一的 formParameters 属性。

POST RAML 中的参数支持

POST parameters support in RAML

api

rest

raml