Rails Grape Swagger中数组示例显示为对象的异常问题咨询

在Rails Grape API中定义了一个嵌套数组字段，代码如下：

expose(
      :users,
      documentation: {
        type: Array,
        desc: 'The pickups and deliveries for specific tours'
      },
      using: Fleetdog::Entities::Users
    )

但访问API文档页面时，示例值显示为哈希而非数组，示例如下：

example value
{ id: 'string',
users: {
  id: 'string',
  name: 'string'
}

请问这是Grape的正常表现吗？

这不是Grape的正常表现，问题出在文档配置仅声明了type: Array，但未明确指定数组内元素的实体类型，导致Grape无法自动生成正确的数组格式示例。

可以通过两种方式修正：

• 方式一：在documentation中补充items字段，明确数组元素的实体类型

  expose(
        :users,
        documentation: {
          type: Array,
          items: { type: Fleetdog::Entities::Users },
          desc: 'The pickups and deliveries for specific tours'
        },
        using: Fleetdog::Entities::Users
      )
  

• 方式二：使用Grape实体的collection方法声明数组类型，替代直接指定type: Array

  expose :users, using: Fleetdog::Entities::Users, documentation: {
    desc: 'The pickups and deliveries for specific tours'
  } do |object|
    collection(object.users, using: Fleetdog::Entities::Users)
  end
  

修改后，API文档中的users字段示例会变为正确的数组格式，类似：

{ id: 'string',
users: [
  { id: 'string', name: 'string' },
  { id: 'string', name: 'string' }
]
}

内容的提问来源于stack exchange，提问作者Petros Kalafatidis