Как определить заголовки в домене чванства - PullRequest
Новая
       29

Как определить заголовки в домене чванства

0 голосов
/ 14 декабря 2018

Я пытаюсь определить некоторые повторно используемые элементы в домене SwaggerHub, но не могу понять, как определить заголовки.

Я пробовал несколько вещей, но все они вызывают ошибки, такие как:

  • $ refs не может соответствовать ни одному из следующих: " # / Definitions ", " # / parameters "
  • должно быть объектом
  • требуется свойство "type"
  • AdditionalProperty "$ ref" существует, когда не разрешено

Полный пример здесь: https://app.swaggerhub.com/domains/batwad/domain-demo/1.0.0

definitions:
  error-list:
    description: Standard error response
    type: object
    properties:
      errors:
        type: array
        items:
          type: string
        readOnly: true

responses:
  bad-request:
    description: Bad request
    headers:
      # these don't error, but the UI docs say "Could not render this component"
      X-Transaction-ID:
        description: Transaction correlation identifier.
        type: string
      Content-Type:
        description: Must be <tt>application/json</tt>
        type: string
    schema:
      $ref: '#/definitions/error-list'

  server-error:
    description: Unexpected error
    headers:
      # says "should be an object" and "cannot match any of blablabla"
      - $ref: '#/parameters/x-transaction-id'
      - $ref: '#/parameters/content-type'
    schema:
      $ref: '#/definitions/error-list'

  service-unavailable:
    description: Service temporarily unavailable
    schema:
      $ref: '#/definitions/error-list'
    headers:
      # says "requires property 'type'" and "$ref not allowed"
      X-Transaction-ID:
        $ref: '#/parameters/x-transaction-id'
      Content-Type:
        $ref: '#/parameters/content-type'

parameters:

  x-transaction-id:
    name: X-Transaction-ID
    in: header
    description: Transaction correlation identifier.
    required: true
    type: string

  content-type:
    name: Content-Type
    in: header
    description: Must be <tt>application/json</tt>
    required: true
    type: string

1 Ответ

0 голосов
/ 14 декабря 2018

Определение ответа bad-request является правильным, и другие ответы должны быть изменены, чтобы выглядеть так же.Таким образом, заголовки ответа должны быть определены в строке - это ограничение спецификации OpenAPI 2.0, она не поддерживает заголовки ответа $ ref'erencing.

$ заголовки ответа ref'erencing возможны вOpenAPI 3.0 , но на момент написания этой статьи (декабрь 2018 г.) SwaggerHub еще не поддерживает синтаксис OAS3 в доменах.

Что касается «Не удалось отобразить этот компонент», это ошибка отображения вSwaggerHub.Отправить отчет об ошибке через чат поддержки в приложении.При этом определения API, использующие ответы от доменов, отображаются правильно. UPD: это исправлено по состоянию на февраль 2019 года.

...