Comment créer une définition d'API dans Swagger qui contient différents objets de différents niveaux?

Question

J'ai essayé de développer une API dans Swagger en utilisant YAML. Je veux avoir une définition de document global qui se lit comme suit dans JSON (exemple):

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

En ce moment je suis en utilisant la fonction allof YAML pour obtenir le contenu de document_info, document_details, page_parameters et extraction_operations et il est me produire le résultat suivant (pas tout à fait attendu):

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

Il est fonctionnel comme ça, mais ce que je voulais était d'avoir quelque chose de plus facile à lire et à travailler avec tout comme ce qui a été mentionné ci-dessus. Ma définition actuelle YAML pour ceci est représenté ci-dessous:

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' 

Est-il possible de formater la façon dont je fais semblant de? Quelqu'un peut-il me donner quelques conseils sur la façon de le faire dans Swagger?

Answer 1

Faites-le! A dû imbriquer des choses comme ceci:

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