如何使用 OpenAPI-3.0 表达 JSON-API 稀疏字段集
How do I express JSON-API sparse fieldsets with OpenAPI-3.0
我正在为我的 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
但我不想为每个资源和字段拼出每个选项。
你的定义是正确的。您可能还需要添加 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
我正在为我的 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
但我不想为每个资源和字段拼出每个选项。
你的定义是正确的。您可能还需要添加 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