web-dev-qa-db-ja.com

OpenAPI 3.0汎用データ型

OpenAPI 3の実際のデータ型を含む一般的な応答型を最もよく説明するにはどうすればよいですか。

簡略化した例：

ApiResponse:
  data: object
  error: string

しかし/ usersエンドポイントは以下を与える必要があります：

ApiResponse<List<User>>

つまり、基本的には次のとおりです。

ApiResponse:
  data: List<User>
  error: string

現時点では不可能のようですが、確認したいだけです。これを行う最善の方法は、すべての呼び出しに対して名前付き応答を作成し、allOfを使用してApiResponseおよび実装データ（特定の値）を参照することです。

swaggeropenapi
12
Jørgen

私はずっとジェネリック型を検索していますが、OpenAPI3でジェネリック型を定義する方法はありません。最も簡単な方法は、allOfと$ refを同時に使用することです。次のようなリストスキーマがあるとします。

List:
   type: object
   properties:
       page_number:
          type: integer
       page_count:
          type: integer

そして本のスキーマは

Book:
   type: object
   properties:
       title:
          type: string
       summary:
          type: string

リストを返すには、パスは次のとおりです。

  /api/v1/books:
      get:
        responses:
          default:  
            description: description text
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/List'
                    - type: object
                      properties:
                        items: 
                          type: array
                          items: 
                            $ref: '#/components/schemas/Book'

結果は

   {
        "page_number": 1,
        "page_count": 10,
        "items": [{
            "title": "title",
            "description": ""
        },
        ... ]
    }

実際、これは本のリストです。ご覧のように、リストのメイン属性を結果とリストアイテムタイプに同時に追加します。他の人にもこのパターンを繰り返すことができます：

  /api/v1/authors:
      get:
        responses:
          default:  
            description: description text
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/List'
                    - type: object
                      properties:
                        items: 
                          type: array
                          items: 
                            $ref: '#/components/schemas/Author'
1
مصطفی

まあ、あなたはタイプobjectをadditionalPropertiesと真の値で使って自由形式のオブジェクトを取得できます。

0
Pablo Santa Cruz