OpenAPI 3.0通用数据类型

Question

如何最好地描述包含OpenAPI 3中的实际数据类型的通用响应类型.

简化示例:

ApiResponse:
  data: object
  error: string

但/ users端点应该给出:

ApiResponse<List<User>>

所以这基本上是:

ApiResponse:
  data: List<User>
  error: string

看起来目前这是不可能的,但只是想确定.我想现在最好的方法是为每个调用创建命名响应,并使用allOf来引用ApiResponse和实现数据:特定值.

Answer 1

我经常搜索泛型类型，但无法在 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'