Определение глобальных параметров

Я готовлю свою документацию по API, выполняя ее вручную, а не автоматически создавая. Там у меня есть заголовки, которые должны быть отправлены всем API-интерфейсам, и не знаете, можно ли определять параметры во всем мире для всего API или нет?

некоторые из этих заголовков являются статическими, а некоторые должны быть установлены при вызове API, но все они одинаковы во всех API-интерфейсах, я не хочу копировать и вставлять параметры для каждого API и каждого метода, поскольку это не будет поддерживаться в будущем.

Я видел статические заголовки по определению API, но нет единого документа для того, как кто-то может их установить или использовать.

Это вообще возможно или нет?

Ответы

Ответ 1

Если вы говорите о параметрах заголовка, отправленных потребителем при вызове API:

Вы можете как минимум определить их раз и навсегда в разделах параметров, а затем ссылаться только на них, когда это необходимо. В следующем примере:

  • CommonPathParameterHeader, ReusableParameterHeader и AnotherReusableParameterHeader определяются раз и навсегда в parameters в корневом каталоге документа и могут использоваться в любом списке параметров
  • CommonPathParameterHeader указывается в разделе parameters путей /resources и /other-resources, а это означает, что для ВСЕХ операций этих путей нужен этот заголовок
  • ReusableParameterHeader ссылается на get /resources, что означает необходимость в этой операции
  • То же самое для AnotherReusableParameterHeader в get /other-resources

Пример:

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
    post:
      responses:
        '204':
          description: Succesfully created.

Если ваш разговор о заголовке отправлен с каждым ответом API К сожалению, вы не можете определить повторно используемые заголовки ответов. Но по крайней мере вы можете определить повторно используемый ответ, содержащий эти заголовки для общего ответа, например 500.

Пример:

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
    post:
      responses:
        '204':
          description: Succesfully created.
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
        '500':
          $ref: '#/responses/Standard500ErrorResponse'

responses:
  Standard500ErrorResponse:
    description: An unexpected error occured.
    headers:
      X-Rate-Limit-Remaining:
        type: integer
      X-Rate-Limit-Reset:
        type: string
        format: date-time

Об OpenAPI (fka. Swagger) Следующая версия

Спецификация OpenAPI (fka. Swagger) будет развиваться и включать в себя определение заголовков ответных ответов среди других вещей (см. https://github.com/OAI/OpenAPI-Specification/issues/563).