如何在 RAML 1.0 中覆盖对象数组属性类型

Posted 2023-02-19

【中文标题】如何在 RAML 1.0 中覆盖对象数组属性类型

【英文标题】：How to override an object array property type in RAML 1.0

【发布时间】：2016-05-22 14:10:03

【问题描述】：

我有一个像这样的通用 Java 类型：

class Response<D> 
  List<D> data;

并希望创建与 RAML 1.0 类似的东西（我是新手）。

我的第一个方法是

types:
  Response:
    type: object
    properties:
      data: object[]

以及使用时

body:
  type: Response
    properties:
      data: MyDataType[]

从 API-Workbench 我总是得到“非法覆盖从响应继承的属性数据”。

另一个想法是使用repeat：

types:
  Response:
    type: object
    properties:
      data: object
      repeat: true

分别

body:
  type: Response
    properties:
      data: MyDataType
      repeat: true

现在非法覆盖消失了，但在 API 控制台中，我现在收到“未捕获的类型错误”。

如何解决？还是我需要一种完全不同的方法？有什么想法吗？

【参考方案1】：

据我了解，Response 正在抽象不同类型的数据，但格式相似。一种方法是使用resourceTypes 抽象响应中的相似性，并在types 中定义您的具体数据。

#%RAML 1.0
title: New API
version: v1
baseUri: http://api.samplehost.com
mediaType: application/json

types:
  User:
    usage: A user in the system    
    properties:
      firstname:
        required: true
      lastname:
        required: true

  ArticleId:
    usage: An id of any article in the system
    type: number

  Article:
    usage: Pattern for any article in the system
    properties:
      id:
        type: ArticleId
        required: true
      created:
        type: date
        required: true

#######################################
# the following captures the similarity:
#######################################

resourceTypes:
  collection:
    get:
      responses:
        200:
          body:
            properties:
              data: <<typename>>[]


###############
# API:
############### 

/user:
  description: All the users
  type:
    collection:
      typename: User

/article:
  description: All the articles
  type:
    collection:
      typename: Article     

【参考方案2】：

我看到以下解决此问题的选项：

筛选测试用例的开源存储库，希望能记录您的需求。我发现这个项目raml-java-parser tests 带有大量测试用例，但第一次尝试时找不到解决方案。 这是一个包含字符串collectionSchema in double angle brackets (from raml-for-jaxrs) 语法的特定测试用例资源，看起来很可疑？ 使用 API 生成预期输入的序列化版本，例如你的List<MyDataType>，并修改生成的输出。例如。使用与第 1 点相同的 raml-java-parser。 查找整个文件规范的参考，包括复杂类型。似乎this 和this 可以包含有趣的信息，例如“带有type 的地图/字典或外部类型可能需要包含的事实。也许this answer link 对此有所帮助。 您问题上的 raml 标签目前只有 37 个用户关注。是否有更通用的标签，以便针对更广泛的受众？

20 分钟前我对 RAML 一无所知，所以不要把这当作一个完整的答案，而是一个快速的猜测。

【参考方案3】：

您说“以及使用时”： 身体： 类型：响应 特性： 数据：MyDataType[]

您已经将上面的“响应”类型定义为具有“数据”属性作为“对象[]”。 “MyDataType”从何而来？只需在此处删除“属性”并仅具有“类型：响应”即可。然后错误应该消失。 也许您希望您的响应类型具有“任何 []”。我不知道你想做什么。也许定义另一个继承您的响应类型的类型。

【讨论】：

也许您错过了 Java 类型声明和问题中提到的泛型，但 any 会删除错误但不记录任何内容，这不是使用端点文档工具的意图。