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

【问题标题】：How to create an API definition in Swagger that contains different objects in different levels?如何在 Swagger 中创建包含不同级别的不同对象的 API 定义？
【发布时间】：2018-02-08 00:28:28
【问题描述】：

我一直在尝试使用 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 中执行此操作的指导吗？

【问题讨论】：

标签： json api yaml swagger

【解决方案1】：

成功了！不得不嵌套这样的东西：

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

【讨论】：