OpenAPI-Specification 2.0 带有正文和标题的帖子答案

【问题标题】：OpenAPI-Specification 2.0 a post with body AND headerOpenAPI-Specification 2.0 带有正文和标题的帖子
【发布时间】：2018-08-30 17:32:44
【问题描述】：

我想在帖子中发送一个对象，但使用 api 密钥。

如何在OpenAPI-Specification 2.0 中描述这一点？

我试过这个（yaml 中的一个子集）：

paths:
  /eau:
    post:
      tags:
        - Pets
      summary: Send a pet
      description: 'Send a pet'
      operationId: sendapet
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: pet
          description: Send a pet
          required: true
          schema:
            $ref: '#/definitions/pet'
        - in: header
          name: api_key

但是在

- in: header
    name: api_key

我收到以下错误：

Schema error at paths['/pet'].post.parameters[1].in
should be equal to one of the allowed values
allowedValues: body
Jump to line 36

Schema error at paths['/pet'].post.parameters[1]
should match exactly one schema in oneOf
Jump to line 36

Schema error at paths['/pet'].post.parameters[1]
should NOT have additional properties
additionalProperty: in, name
Jump to line 36

【问题讨论】：

标签： yaml swagger restful-architecture swagger-2.0

【解决方案1】：

报错是因为缺少header参数type。

但是，API 密钥与身份验证/授权相关，因此应使用 securityDefinitions 和 security 关键字而不是标头参数来描述它们：

securityDefinitions:
  apiKey:
    type: apiKey
    in: header
    name: api_key

security:
  - apiKey: []

更多信息：API Keys

【讨论】：