Как использовать $ ref в схеме в OpenAPI 3.0? - PullRequest
Новая
       9

Как использовать $ ref в схеме в OpenAPI 3.0?

0 голосов
/ 26 ноября 2018

Я хочу представить следующий JSON как schema в определении API OpenAPI 3.0: 

{
get-question: {
  question-id:string
  }
}

Пока я написал: 

components:
  schemas:
  #schema of a question-id
    QuestionID:   #{question-id: string}
      properties:
        question-id:
          type: string
      required:
        - question-id

  #schema of a get-question request which contains a question id      
    GetQuestion: #{get-question: {question-id:string}}
      properties:
        get-questions:
          type: $ref:'#/components/schemas/QuestionID'
      required:
        - get-questions

но яполучить эти ошибки в редакторе Swagger: 

Schema error at components.schemas['GetQuestion']
should have required property '$ref'
missingProperty: $ref
Jump to line 79
Schema error at components.schemas['GetQuestion']
should match exactly one schema in oneOf
Jump to line 79
Schema error at components.schemas['GetQuestion'].properties['get-questions']
should have required property '$ref'
missingProperty: $ref
Jump to line 81
Schema error at components.schemas['GetQuestion'].properties['get-questions']
should match exactly one schema in oneOf
Jump to line 81
Schema error at components.schemas['GetQuestion'].properties['get-questions'].type
should be equal to one of the allowed values
allowedValues: array, boolean, integer, number, object, string
Jump to line 82

Каков правильный синтаксис для $ref?

1 Ответ

0 голосов
/ 26 ноября 2018

$ref используется вместо из type, а не как значение type.Также обратите внимание на пробел после : для разделения ключа и значения в YAML. 

        get-questions:
          $ref: '#/components/schemas/QuestionID'

Вам также необходимо добавить type: object к схемам QuestionID и GetQuestion, чтобы указать, что они являются объектами;одного ключевого слова properties недостаточно.

В одном из имен свойств, по-видимому, также есть опечатка - это get-questions (множественное число) в схеме GetQuestion, но get-question (единственное)в вашем примере JSON.Я думаю, это должно быть get-question.

Полный пример: 

components:
  schemas:
    # schema of a question-id
    QuestionID:      # {question-id: string}
      type: object   # <-----
      properties:
        question-id:
          type: string
      required:
        - question-id

    #schema of a get-question request which contains a question id      
    GetQuestion:     # {get-question: {question-id:string}}
      type: object   # <-----
      properties:
        get-question:
          $ref: '#/components/schemas/QuestionID'   # <-----
      required:
        - get-questions
...