使用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.

对特定库的请求应返回以上所有内容，包括额外的参数书:

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"进行简单建模，该附加的"ExtendedLibrary"包含基础库的所有响应和附加的books属性.

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?

推荐答案

如评论部分所述，这可能是

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屋！