如何在Swagger中创建一个包含不同级别对象的API定义？

Question

我一直在尝试使用YAML在Swagger中开发API。 我想要一个全局文档定义，该定义在JSON（示例）中的内容如下：

{
  "document_info" : 
  {
    "name" : "string",
    "file" : "base64"
  },
  "document_details":
  {
    "author" : "string",
    "keywords" : "string"
    },
  "page_parameters" :
  {
    "start_page" : "integer",
    "end_page" : "integer"
  },
  "extraction_operations":
  {
    "extract_toc" : "bool",
    "extract_page" : "bool"
  }
}

现在，我正在使用allOf YAML函数从document_info，document_details，page_parameters和extract_operations中获取内容，并且正在产生以下结果（不太符合预期）：

{
  "file": "string",
  "name": "string",
  "author": "string",
  "subject": "string",
  "title": "string",
  "creator": "string",
  "keywords": [
    "string"
  ],
  "startPage": 0,
  "endPage": 0,
  "extractCover": true,
  "extractDetails": true,
  "extractTOC": true,
  "extractPages": true,
  "extractClipped": true,
  "extractFiles": true,
  "extractImages": true,
  "extractLinks": true,
  "extractMerge": true
}

它的功能是这样的，但是我想要的是像上面提到的那样具有一种易于阅读和使用的方式。 我目前对此的YAML定义如下所示：

definitions:
    APIFileExtract:
        type: object
        required:
            - file
            - name
        properties:
            file:
                type: string
            name:
                type: string
    APIFileExtractWithPageParams:
        allOf:
            - $ref: '#/definitions/APIFileExtract'
            - $ref: '#/definitions/APIFileExtractPageParams'
    APIFileExtractDetails:
        allOf:
            - $ref: '#/definitions/APIFileExtract'
            - type: object
        properties:
            author:
                type: string
            subject:
                type: string
            title:
                type: string
            creator:
                type: string
            keywords:
                type: array
            items:
                type: string
    APIFileExtractMethods:
        type: object
        properties:
            extractCover:
                type: boolean
            extractDetails:
                type: boolean
            extractTOC:
                type: boolean
            extractPages:
                type: boolean
            extractClipped:
                type: boolean
            extractFiles:
                type: boolean
            extractImages:
                type: boolean
            extractLinks:
                type: boolean
            extractMerge:
                type: boolean
    APIFileExtractPageParams:
        type: object
        properties:
            startPage:
                type: integer
            endPage:
                type: integer 
    APIFileExtractGlobal:
        allOf:
          - $ref: '#/definitions/APIFileExtract'
          - $ref: '#/definitions/APIFileExtractDetails'
          - $ref: '#/definitions/APIFileExtractPageParams'
          - $ref: '#/definitions/APIFileExtractMethods'

是否可以格式化我假装的方式？ 有人可以给我一些在Swagger中如何做的指导吗？

Answer 1

做好了！ 不得不嵌套这样的东西：

APIFileExtractGlobal:
    type: object
    properties:
      DocumentInfo:
        $ref: '#/definitions/APIFileExtract'
      DocumentDetails:
        $ref: '#/definitions/APIFileExtractDetails'
      PageParameters:
        $ref: '#/definitions/APIFileExtractPageParams'
      ExtractionMethods:
        $ref: '#/definitions/APIFileExtractMethods'