RAML：对具有不同属性的GET和POST使用相同的数据类型

Question

所以我从我的RAML规范中提取JSON模式以验证GET方法中的输出以及POST方法中的输入。

这种类型的每个实体都有一个“必需的”ID属性 - 至少在将这些实体列入“获取项目”或“获取集合”请求时是必需的。但是，当验证收到的帖子数据以创建这样的实体时，显然不需要ID（如果它仍然发送则丢弃）。

什么是最好的DRY方式来获得GET请求所需的此ID属性，但不是必需的，甚至更好的不存在于POST请求的类型中？

TL; DR：开始阅读下面;）

示例使其更容易理解：

对于GET请求，类型应如下：

properties:
  id:
  something1: 
  something2?: 

对于POST请求，类型应为：

properties:
  something1: 
  something2?: 

无需单独定义，也不必使用继承来为每个资源创建两种类型。

理想情况下，我会这样解决，但这似乎不起作用：

get:
  description: Retrieve a list of <<resourcePathName|!uppercamelcase>>.
  responses:
    200:
      body:
        application/json:
          type: [ entity_id_object, <<resourcePathName|!singularize|!uppercamelcase>> ][]
          example: <<exampleCollection>>

和entity_id_object只是：

entity_id_object:
   properties:
     id:

我认为这是因为<<resourcePathName|!singularize|!uppercamelcase>>不适用于这种组合。

Answer 1

如果没有两种类型，我想不出一种方法。但是这个例子至少只让你传递一种类型，并自动将'NoId'附加到POST请求的类型名称。

#%RAML 1.0
title: My API
version: v1
mediaType: application/json

types:
  ResponseNoId:
    properties:
      something1: 
      something2?:
  ResponseId:
    properties:
      id:
      something1: 
      something2?:
  Response:
    ResponseNoId|ResponseId

resourceTypes:
  collection:
    usage: Use this resourceType to represent a collection of items
    description: A collection of <<resourcePathName|!uppercamelcase>>
    get:
      description: |
        Get all <<resourcePathName|!uppercamelcase>>,
        optionally filtered
      is: [ hasResponseCollection: { typeName: <<typeName>> } ]
    post:
      description: |
        Create a new <<resourcePathName|!uppercamelcase|!singularize>>
      is: [ hasRequestItem: { typeName: <<typeName>> } ]
  item:
    usage: Use this resourceType to represent any single item
    description: A single <<typeName>>
    get:
      description: Get a <<typeName>>
      is: [ hasResponseItem: { typeName: <<typeName>> } ]

traits:
  hasRequestItem:
    body:
      application/json:
        type: <<typeName>>
  hasResponseItem:
    responses:
      200:
        body:
          application/json:
            type: <<typeName>>
  hasResponseCollection:
    responses:
      200:
        body:
          application/json:
            type: <<typeName>>[]

/myResource:
  type: { collection: { typeName: Response } }
  get:

  /{id}:
    type: { item: { typeName: Response } }
  post:
    body:
      application/json:

Answer 2

您可以将id字段标记为readOnly以使意图清晰，尽管它不会影响数据的验证方式。

要影响验证，可以创建“读取”类型和“写入”类型，其中“读取”类型具有额外的必需id属性。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "MyWriteEntity": {
      "type": "object",
      "properties": {
        "something1": { "type": "string"},
        "something2": { "type": "string"}
      },
      "required": "something1"
    },
    "MyReadEntity": {
      "allOf": [
        { "$ref": "#/definitions/MyWriteEntity" },
        {
          "id": { "type": "string", "readOnly": true},
          "required": ["id"]
        }
      ]
    }
  }
}