RAML 中的 POST 参数支持

Posted 2023-02-19

【中文标题】RAML 中的 POST 参数支持

【英文标题】：POST parameters support in RAML

【发布时间】：2016-05-28 01:54:48

【问题描述】：

我想问一下RAML中是否支持POST参数。如果有 - 语法是什么。我大致浏览了规范0.8 和规范1.0（实际上我必须使用0.8，因为许多工具还不支持1.0）。我没有找到 POST 参数支持，但也许我错过了一些东西。

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

HTTP普通参数，key=value，每个参数一行，如

name=John Doe amount=5 不是很方便（例如没有嵌套）

参数作为 JSON 对象，只是一个 JSON 的所有语法都允许（服务器端需要解析这个 json）；如：

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

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

【问题讨论】：

选项 1 使用什么内容类型？

@DavidDossot 没关系，我可以稍后调整。问题是关于概念的。您可以假设name 的类型为string，amount 的类型为number。

这很重要，因为内容类型是 RAML 中请求正文规范的一部分。另外我对这种编码不熟悉，所以我希望在知道类型后能更多地了解它。

对于选项 2，这很简单，如下所示的@Pedro。对于选项 1，问题是要找到一种模式语言，它可以描述具有类型的多行类似属性的文档。

@DavidDossot 选项一实际上是默认的 HTTP POST 参数处理。 JSON（选项 2）是它的派生词...

【参考方案1】：

正如参考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 属性。

【讨论】：

感谢 raml 1.0 示例！

【参考方案2】：

@Pedro 已经涵盖了选项 2，所以这里是选项 1。根据 cmets 中的讨论，使用的编码似乎是 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

【参考方案3】：

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

【讨论】：

所以 JSON 模式可以用于请求模式和响应模式定义，对吧？

可以，见：github.com/raml-org/raml-spec/blob/master/raml-0.8.md#responses

谢谢两位，先生。抱歉，我不能同时接受两者，我接受@DavidDossot，因为这似乎更难。