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

问题描述

我正在为我的 API 实施 OpenAPI-3.0 规范，我计划使用 sparsefieldsets 作为 GET 的参数.参数的示例使用style=deepObject 有点稀疏，所以我不确定我是否完全正确.

I'm implementing an OpenAPI-3.0 spec for my API, and I plan on using sparse fieldsets as a parameter for GETs. The examples for parameters using style=deepObject are a little sparse, so I'm not sure if I've got this exactly right.

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

我可以同时使用 deepObject 和 additionalProperties 选项吗?

Can I combine both the deepObject and additionalProperties options?

我想支持这样的灵活查询参数输入:GET/articles?include=author&fields[articles]=title,body&fields[people]=name但我不想为每个资源和领域详细说明每个选项.

I want to support flexible query parameter inputs like this:GET /articles?include=author&fields[articles]=title,body&fields[people]=namebut I don't want to have to spell out every single option for each resource and field.

推荐答案

你的定义是正确的.您可能还需要添加 allowReserved: true 这样=title,body中的逗号就不是百分比编码的，可以添加参数example的值用于文档目的:

Your definition is correct. You might also need to add allowReserved: true so that the comma in =title,body is not percent-encoded, and you can add a parameter example value for documentation purposes:

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

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

When using "try it out" in Swagger UI, enter the parameter value in the JSON format like so:

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

Swagger UI 会将参数序列化为

Swagger UI will serialize the parameter as

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

这篇关于如何使用 OpenAPI-3.0 表达 JSON-API 稀疏字段集的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！