web-dev-qa-db-ja.com

Swaggerドキュメントでオブジェクトタイプのクエリパラメータを使用する

URLのオブジェクトパラメータをクエリ文字列としてエンコードしたいGETルートがあります。

Swaggerドキュメントを作成すると、基本的に、schemaタイプパラメータでobject/queryタイプを使用できないというエラーが発生します。

paths:
  /mypath/:
    get:
      parameters
        - in: path
          name: someParam
          description: some param that works
          required: true
          type: string
          format: timeuuid #good param, works well
        - $ref: "#/parameters/mySortingParam" #this yields an error

parameters:
  mySortingParam
    name: paging
    in: query
    description: Holds various paging attributes
    required: false
    schema:
      type: object
      properties:
        pageSize:
          type: number
        cursor:
          type: object
          properties:
            after:
              type: string
              format: string

オブジェクト値を持つリクエストクエリパラメータは、実際のリクエストにエンコードされます。

Swaggerは画面の上部にエラーを表示しますが、オブジェクトはSwagger UIエディターで正しくレンダリングされますが、そのエラーはドキュメントの上部に表示されます。

swaggerswagger-uiquery-parameters
7
Vee6

クエリパラメータはプリミティブ型のみをサポートしているため、Swagger仕様のクエリパラメータとして「オブジェクト」を使用できるとは思いません（ https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0 .md＃data-types ）

12
William Cheng

これは、OpenAPI3.0で可能になりました。

parameters:
  - in: query
    name: values
    schema:
      type: object
      properties:
        genre_id: 
          type: integer
        author_id:
          type: integer
        title:
          type: string
      example:
       {
         "genre_id": 1,
         "author_id": 1
       }
    style: form
    explode: true

ここでは、styleおよびexplodeキーワードを使用して、パラメーターのシリアル化方法を指定できます。

  • styleは、複数の値を区切る方法を定義します。可能なスタイルは、パラメーターの場所（パス、クエリ、ヘッダー、またはCookie）によって異なります。
  • explode（true/false）は、配列とオブジェクトが配列アイテムまたはオブジェクトプロパティごとに個別のパラメーターを生成するかどうかを指定します。

上記の例では、URLは次のようになります。

https://ebookstore.build/v1/users/books/search?genre_id=1&author_id=1

OpenAPI v3でのパラメーターの説明とパラメーターのシリアル化の詳細については、 ここ を参照してください。

4
Chaythanya nair

これは可能ですが、OpenAPI2.0では不可能です。 OpenAPI 3.0は、これがどのように可能であるかをここで説明しています。

https://swagger.io/docs/specification/describing-parameters/

parameters:
- in: query
  name: filter
  # Wrap 'schema' into 'content.<media-type>'
  content:
    application/json:  # <---- media type indicates how to serialize / deserialize the parameter content
      schema:
        type: object
        properties:
          type:
            type: string
          color:
            type: string

それまでの間、クエリパラメータを単純な古い文字列型として使用し、手動でシリアル化を実行してから、必要に応じてクエリパラメータを設定することができます。これは、SwaggerUIがOpenAPI3.0を完全にサポートするまで私が行っていることです。

2
Daniel Maclean