如何使用 OpenAPI-3.0 表达 JSON-API 稀疏字段集

Question

我正在为我的 API 实现 OpenAPI-3.0 规范，并且我计划使用稀疏字段集作为 GET 的参数。使用 style=deepObject 的参数示例有点稀疏，所以我不确定我是否完全正确。

- in: query
  name: fields
  style: deepObject
  schema:
    type: object
    additionalProperties:
      type: string

我可以结合 deepObject 和 additionalProperties 选项吗？

我想支持这样的灵活查询参数输入： GET /articles?include=author&fields[articles]=title,body&fields[people]=name 但我不想为每个资源和字段拼出每个选项。

Answer 1

你的定义是正确的。您可能还需要添加，allowReserved: true以便逗号=title,body不是百分比编码，并且您可以添加一个参数example值用于文档目的：

- in: query
  name: fields
  style: deepObject
  allowReserved: true
  schema:
    type: object
    additionalProperties:
      type: string
    example:
      articles: title,body
      people: name

在 Swagger UI 中使用“试用”时，以 JSON 格式输入参数值，如下所示：

{
  "articles": "title,body",
  "people": "name"
}

Swagger UI 会将参数序列化为

?fields[articles]=title,body&fields[people]=name