web-dev-qa-db-ja.com

オブジェクトのリストを含むOpenAPIクエリ文字列パラメーター

OpenAPI のようなクエリ文字列でドキュメント化しようとしています

filtered[0][id]=code&filtered[0][value]=12345

プロパティidおよびvalueのオブジェクトのリストが含まれています。

私のyamlドキュメントは次のようになります

parameters:
    - name: filtered
      in: query
      description: filters to be applied
      explode: true
      style: deepObject
      schema:
        type: array
        items:
          properties:
            id:
              description: name of the field to be filtered
              type: string
            value:
              description: value of the filter
          type: object

問題は次のとおりです。style: deepObjectオプションは1つのレベルでのみ機能し、オブジェクトが実際に存在する2番目のレベルでは機能しないようです。つまり、次のようなクエリ文字列が必要です。

?sorted[0]=%7B%0A%20%20%22id%22%3A%20%22string%22%2C%0A%20%20%22value%22%3A%20true%0A%7D

オブジェクトは、idおよびvalueキーを持つ配列としてシリアル化されていません。

これを解決する方法はありますか？

jsonswaggerjsonschemaopenapi
9
marcosh

これはOpenAPI 3.0.3以降では不可能です

OpenAPI 3.0仕様では現在、deepObjectの動作が単純なオブジェクト（プリミティブプロパティ付き）に対してのみ定義されています。

{
  "id": 5,
  "name": "Bob"
}

ただし、 配列は不可 および ネストされたオブジェクトは不可 です。

配列とネストされたオブジェクトの動作は定義されていないため、クエリ文字列を記述する方法は実際にはありません。技術的には、filtered[0][id]、filtered[0][value]などを個別のクエリパラメータとして定義するのが唯一の方法です。


（既存のAPIを記述するのではなく）新しいAPIを設計する場合は、代わりにリクエストの本文でオブジェクトの配列を渡すことを検討してください。

3
Helen

名前が示すように、:)、deepObjectスタイルは、配列ではなく、「ネストされたオブジェクトの簡単なレンダリング方法を提供する」だけです。少なくともバージョン3.0.1では、オブジェクトにのみ適用されます。

仕様では「そのような例が提供されていない」ため、ネストされたオブジェクトでさえツールによってまだサポートされていない可能性があることに注意してください。

したがって、あなたのフォーマットはOpen APIと互換性がありませんが、正規表現に従うパラメータとしてクエリを定義できる場合があります。そのような場合、私は通常最善を尽くしますが、いくつかの説明を提供します

https://swagger.io/specification/

更新。どうやら、誰かがネストされたオブジェクトの「説明的なエラー」メッセージを要求した後、ネストされたオブジェクトのサポートがswagger-js v.3.9に追加されました。 https://github.com/swagger-api/swagger-js/pull/145

1
Serge