使用 Swagger/OpenAPI 创建可扩展模型 [英] Creating an extendible model using Swagger/ OpenAPI

问题描述

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

In my API i would like to have a simple model for my collection and a more elaborate model for my individual resource. For example:

/libraries 上的 GET 请求应返回

a GET request on /libraries should 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.

虽然对特定库的请求应返回上述所有内容，包括额外的参数books:

whilst a request to a specific library should return all of the above including an extra parameter books:

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

So a GET request to libraries/{library_id} should 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"，其中包含基础库的所有响应和额外的书籍属性.

I would very much like to not have to define a "BaseLibrary" twice and would want to simple model an additional "ExtendedLibrary" which contains all the responses of a base library and the additional books property.

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

I tried a lot of different things, with the closest to succes being the following definitions:

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 模型中?

However this gives me a "Extra JSON reference properties will be ignored: books" warning and the output seems to ignore this extra property. Is there a clean way to handle my problem? Or am I just going to have to copy paste my whole BaseLibrary model into my ExtendedLibrary model?

推荐答案

如评论部分所述，这可能与 另一个问题，但值得在这个特定示例的上下文中重复答案.解决方法是在ExtendedLibrary的定义中使用allOf属性:

As mentioned in the comments section, this may be a duplicate of another question, but it's worth repeating the answer in the context of this particular example. The solution is to use the allOf property in the definition of 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"

根据我的经验，Swagger UI 可以正确地对此进行可视化.当我将操作响应定义为 ExtendedLibrary Swagger UI 显示此示例:

In my experience, Swagger UI visualizes this correctly. When I define an operation response to be ExtendedLibrary Swagger UI shows this example:

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

此外，Swagger Codegen 做了正确的事.至少在生成 Java 客户端时，它会创建一个正确扩展 BaseLibrary 的 ExtendedLibrary 类.

Also, Swagger Codegen does the right thing. At least when generating a Java client, it creates an ExtendedLibrary class that correctly extends BaseLibrary.

这篇关于使用 Swagger/OpenAPI 创建可扩展模型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！