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

Question

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

/libraries 上的 GET 请求应该 return

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.

虽然对特定图书馆的请求应该 return 以上所有内容包括一个额外的参数 books:

所以对 libraries/{library_id} 的 GET 请求应该 return:

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"

然而，这给了我一个 "Extra JSON reference properties will be ignored: books" 警告，输出似乎忽略了这个额外的属性。有没有一种干净的方法来处理我的问题？还是我只需要将我的整个 BaseLibrary 模型复制粘贴到我的 ExtendedLibrary 模型中？

Answer 1

如评论部分所述，这可能与 another question 重复，但值得在此特定示例的上下文中重复答案。解决办法是在ExtendedLibrary的定义中使用allOf属性:

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"

根据我的经验，Swagger UI 正确地形象化了这一点。当我将操作响应定义为 ExtendedLibrary Swagger UI 显示此示例：

{
  "library_id": "string",
  "display_name": "string",
  "href": "string",
  "books": [
    {
      "title": "string",
      "author": "string"
    }
  ]
}

另外，Swagger Codegen 做对了。至少在生成 Java 客户端时，它会创建一个正确扩展 BaseLibrary.

的 ExtendedLibrary class

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

Creating an extendible model using Swagger/ OpenAPI

swagger

definitions

openapi