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

我正在为我的 API 实现 OpenAPI-3.0 规范，并且我计划使用稀疏字段集 https://jsonapi.org/format/#fetching-sparse-fieldsets作为 GET 的参数。的例子参数 https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#parameterObject使用 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但我不想详细说明每个资源和领域的每个选项。

你的定义是正确的。您可能还需要添加allowReserved: true https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#user-content-parameterallowreserved这样逗号中=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 中使用“try it out”时，请输入 JSON 格式的参数值，如下所示：

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

Swagger UI 会将参数序列化为

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