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

Question

我正在为我的API实现OpenAPI-3.0规范，我计划将sparse fieldsets用作GET的参数。使用style = deepObject的parameters的示例有点稀疏，因此我不确定是否正确。

- 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用户界面中使用“试用”时，请按JSON格式输入参数值，如下所示:

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

Swagger UI会将参数序列化为

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