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

Question

我正在为我的 API 实施 OpenAPI-3.0 规范，我计划使用 sparse fieldsets as a parameter for GETs. The examples for parameters using 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 中使用 "try it out" 时，以 JSON 格式输入参数值，如下所示：

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

Swagger UI 会将参数序列化为

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

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

How do I express JSON-API sparse fieldsets with OpenAPI-3.0

openapi

json-api