使用Swagger / OpenAPI创建可扩展模型

Question

在我的API中，我想为我的收藏设计一个简单的模型，并为我的个人资源提供更精细的模型。例如：

/libraries上的GET请求应该返回

BaseLibrary:
    type: object
    properties:
        library_id:
          type: string
          description: The id of the library
        display_name:
          type: string
          description: Name of the library
        href:
          type: string
          description: The URI linking to this library.

虽然对特定图书馆的请求应该返回以上所有内容，包括额外的参数书：

因此，libraries/{library_id}的GET请求应返回：

ExtendedLibrary:
    type: object
    properties:
        library_id:
          type: string
          description: The id of the library
        display_name:
          type: string
          description: Name of the library
        href:
          type: string
          description: The URI linking to this library.
        books:
          type: array
          description: The books in this library
          items:
            $ref: "#/definitions/books"

我非常希望不必两次定义“BaseLibrary”，并希望简单地建模一个额外的“ExtendedLibrary”，其中包含基本库的所有响应和附加书籍属性。

我尝试了很多不同的东西，最接近成功的是以下定义：

definitions:
  BaseLibrary:
    type: object
    properties:
        library_id:
          type: string
          description: The id of the library.
        display_name:
          type: string
          description: Name of the library
        href:
          type: string
          description: The URI linking to this library.

  ExtendedLibrary:
    type: object
    properties:
      $ref: "#/definitions/BaseLibrary/properties"
      books:
        type: array
        description: The available books for this library.
        items:
          $ref: "#/definitions/Book"

然而，这给了我一个“额外的JSON引用属性将被忽略：书籍”警告，输出似乎忽略了这个额外的属性。有没有一个干净的方法来处理我的问题？或者我只是要将我的整个BaseLibrary模型粘贴到我的ExtendedLibrary模型中？

Answer 1

如评论部分所述，这可能与http://hadoop.apache.org/docs/stable2/api/org/apache/hadoop/mapreduce/Job.html重复，但在此特定示例的上下文中值得重复答案。解决方案是在ExtendedLibrary：

的定义中使用definitions: Book: type: object properties: title: type: string author: type: string BaseLibrary: type: object properties: library_id: type: string description: The id of the library display_name: type: string description: Name of the library href: type: string description: The URI linking to this library. ExtendedLibrary: type: object allOf: - $ref: '#/definitions/BaseLibrary' - properties: books: type: array description: The books in this library items: $ref: "#/definitions/Book" 属性

ExtendedLibrary

根据我的经验，Swagger UI可以正确地显示这一点。当我将操作响应定义为{ "library_id": "string", "display_name": "string", "href": "string", "books": [ { "title": "string", "author": "string" } ] } 时，Swagger UI显示了这个示例：

ExtendedLibrary

此外，Swagger Codegen也做对了。至少在生成Java客户端时，它会创建一个正确扩展BaseLibrary的{​​{1}}类。