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和extraction_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'

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

1 个答案: