Как правильно определить примеры в разделе компонентов / примеров в OpenAPI 3.0? - PullRequest
Новая
       5

Как правильно определить примеры в разделе компонентов / примеров в OpenAPI 3.0?

1 голос
/ 03 марта 2020

Я пытаюсь использовать OpenAPI 3, YAML для создания определения API. Я использовал документы https://swagger.io/docs/specification/adding-examples/ о том, как добавлять примеры.

В моем определении API у меня есть конечная точка, которая возвращает массив JSON. Мне успешно удалось заставить этот пример работать как часть определения API, но сейчас я пытаюсь извлечь пример и переместить его в раздел components, но мне не повезло.

Это это то, что у меня сейчас: 

paths: 
  /report:
    get:
      parameters: 
        - in: query
          name: dateFrom
          schema:
            type: string
            format: date
          required: true
          example: "2020-01-21"
          description: The start date range
        - in: query
          name: dateTo
          schema:
            type: string
            format: date
          required: true
          example: "2020-02-01"
          description: The end date range
      summary: Used by Anayltics to produce reports showing submission that cannot be determined by GA
      responses:
        '200':
          description: valid response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validresponse'
              example:
                analytics:
                  - date: "2019-01-20"
                    submission: "BaTD"
                    source: "Internal"
                    model: "Model"
                    count: 2
                  - date: "2019-02-20"
                    submission: "BaTD"
                    source: "3rd Party"
                    model: "Model"
                    count: 1  
                  - date: "2019-01-20"
                    submission: "Contact Us"
                    source: "Internal"
                    model: ""
                    count: 20
                  - date: "2019-02-20"
                    submission: "Contact Us"
                    source: "3rd Party"
                    model: ""
                    count: 1

Я сейчас пытаюсь извлечь пример из встроенного определения и переместить его в раздел components: 

components:
  examples:
    reportResponse:
      analytics:
      - date: "2019-01-20"
        submission: "BaTD"
        source: "Internal"
        model: "Model"
        count: 2
      - date: "2019-02-20"
        submission: "BaTD"
        source: "3rd Party"
        model: "Model"
        count: 1  
      - date: "2019-01-20"
        submission: "Contact Us"
        source: "Internal"
        model: ""
        count: 20
      - date: "2019-02-20"
        submission: "Contact Us"
        source: "3rd Party"
        model: ""
        count: 1

Но я сообщение об ошибке в строке с reportResponse:

НЕ ДОЛЖНО иметь дополнительные свойства AdditionalProperty: analytics

При просмотре документации в предоставленных примерах упоминается, что массив не может быть частью examples, но только example.

Если я заменю components на example вместо examples, тогда я получаю ошибку в components.

Могу ли я иметь массив JSON, определенный в components | examples, или это невозможно?

Если это возможно, что мне нужно изменить, чтобы он работал?

1 Ответ

0 голосов
/ 03 марта 2020

Добавьте узел value между именем примера (reportResponse) и значением (analytics: ...): 

components:
  examples:
    reportResponse:
      summary: Short description of this example
      value:   # <--------
        analytics:
        - date: "2019-01-20"
          submission: "BaTD"

Теперь вы можете ссылаться на этот пример следующим образом: 

      responses:
        '200':
          description: valid response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validresponse'
              examples:      # <--------
                reportResponse:
                  $ref: '#/components/examples/reportResponse'
...