Как правильно документировать ответы text / csv в документах swagger / yaml? - PullRequest
Новая
       41

Как правильно документировать ответы text / csv в документах swagger / yaml?

1 голос
/ 13 января 2020

У меня есть несколько конечных точек API, которые возвращают text/csv содержимое в своих ответах. Как мне это документировать? Вот что у меня сейчас есть: 

  /my_endpoint:
    get:
      description: Returns CSV content
      parameters:
        - $ref: '#/components/parameters/myParemeters'
      responses:
        200:
          headers:
            $ref: '#/components/headers/myHeaders'
          content: text/csv

Как есть, это не работает, и я получаю заметку в предварительном просмотре Swagger:

Не удалось отобразить этот компонент, см. консоль.

Вопрос в том, как правильно отобразить содержимое ответов CSV? Я нахожу, работает ли, если я добавляю схему, что-то вроде этого: 

...
  content:
      text/csv:
        schema:
          type: array
          items:
            type: string
...

Но не должно быть схемы, так как это CSV. Итак, чтобы go вернуться к вопросу, как правильно описать содержание ответа csv?

1 Ответ

1 голос
/ 13 января 2020

Ваш первый пример неверный синтаксис. Замените на: 

      responses:
        '200':
          content:
            text/csv: {}  # <-----

          # Also note the correct syntax for referencing response headers:
          headers:
            Http-Header-Name:  # e.g. X-RateLimit-Remaining
              $ref: '#/components/headers/myHeader'

components:
  headers:
    myHeader:
      description: Description of this response header
      schema:
        type: string

Что касается вашего второго примера, в спецификации OpenAPI не приводятся примеры ответов CSV. Таким образом, schema может быть type: string, или массивом строк, или пустой схемой {} (это означает «любое значение»), или чем-то еще. Фактический поддерживаемый синтаксис может зависеть от инструмента. Не стесняйтесь обращаться за разъяснениями в хранилище спецификаций OpenAPI .

...