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

Question

我正在為我的API實現OpenAPI-3.0規范，我計划將稀疏字段集用作GETs的參數。 使用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用戶界面中使用“試用”時，請按JSON格式輸入參數值，如下所示：

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

Swagger UI會將參數序列化為

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