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'

Answer 2

好吧，您可以将类型object与具有真实值的additionalProperties一起使用，以获取自由格式的对象。

OpenAPI 3.0通用数据类型

2 个答案: