CODEWITHSUNDEEP
jsonapiyamlswagger
Henrique Ferreira
Henrique Ferreira

Reputation: 143

How to create an API definition in Swagger that contains different objects in different levels?

I've been trying to develop an API in Swagger using YAML. I want to have a global document definition that reads as it follows in JSON (example):

{
  "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"
  }
}

Right now I'm using allOf YAML function to get the contents from document_info, document_details, page_parameters and extraction_operations and it is producing me the following result (not quite the expected):

{
  "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
}

It is functional like this but what I wanted was to have something way easier to read and to work with just like what was mentioned above. My current YAML definition for this is represented bellow: 

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'

Is it possible to format the way I pretend to? Can someone give me some guidelines on how to do it in Swagger?

Upvotes: 0

Views: 81

Answers (1)

Henrique Ferreira
Henrique Ferreira

Reputation: 143

Made it! Had to nest things like this:

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

Upvotes: 1

Related Questions