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

时间:2017-08-30 10:23:42

标签: json api yaml swagger

我一直在尝试使用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中做到这一点的指导吗?

1 个答案:

答案 0 :(得分:1)

做到了! 不得不嵌套这样的东西:

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